Important: SOAP Toolkit Update

Java Prerequisites

C# Prerequisites

PHP Prerequisites

Java Migration Steps

Add these dependencies to the

pom.xml

file:

<dependencies>
  <dependency>
    <groupId>jakarta.xml.ws</groupId>
    <artifactId>jakarta.xml.ws-api</artifactId>
    <version>4.0.2</version>
  </dependency>
  <dependency>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>jaxws-rt</artifactId>
    <version>4.0.3</version>
    <scope>runtime</scope>
  </dependency>
  <dependency>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>jaxws-ri</artifactId>
    <version>4.0.3</version>
    <type>pom</type>
  </dependency>
  <dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15to18</artifactId>
    <version>1.78</version>
  </dependency>
  <dependency>
    <groupId>org.apache.santuario</groupId>
    <artifactId>xmlsec</artifactId>
    <version>4.0.3</version>
  </dependency>
</dependencies>

Add this plugin to the

pom.xml

file:

<build>
  <plugins>
    <plugin>
      <groupId>com.sun.xml.ws</groupId>
      <artifactId>jaxws-maven-plugin</artifactId>
      <version>4.0.3</version>
      <configuration>
	  <wsdlUrls>
           <wsdlUrl>https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.219.wsdl</wsdlUrl>
        </wsdlUrls>
        <keep>true</keep>
        <packageName>com.cybersource.stub</packageName>
        <sourceDestDir>src/main/java</sourceDestDir>
      </configuration>
    </plugin>
  </plugins>
</build>

Check the value that is set in the

wsdlUrl

tag, and update the version if necessary. The highest version of the WSDL that can be supported is 1.219.

Run this command in your terminal:

mvn clean jaxws:wsimport

Find these lines in your existing code:

TransactionProcessorLocator service = new 
    TransactionProcessorLocator();

URL endpoint = new URL(SERVER_URL);

ITransactionProcessorStub stub = 
    (ITransactionProcessorStub) service.getportXML
    (endpoint);

stub._setProperty(WSHandlerConstants.USER, request
    .getMerchantID());

Replace them with these lines:

TransactionProcessor service = new TransactionProcessor();

service.setHandlerResolver(portInfo - >{
  List < Handler > handlerList = new ArrayList < >();
  handlerList.add(new BinarySecurityTokenHandler());
  return handlerList;
});

ITransactionProcessor stub = service.getPortXML();

Copy these files to your project directory:

BinarySecurityTokenHandler.java
PropertiesUtil.java
SecurityUtil.java

Add a

toolkit.properties

file in the

src/main/resources

folder in your project. The

toolkit.properties

file must contain this content:

MERCHANT_ID = <your_merchant_id>
LIB_VERSION = 4.0.3
KEY_ALIAS = <your_certificate_key_alias>
KEY_FILE = <your_certificate_file>
KEY_PASS = <your_certificate_password>
KEY_DIRECTORY = src/main/resources

If you want to use your own properties file, you can make these changes in the

PropertiesUtil.java

file.

Add your P12 certificate to your key directory.

Run these commands in your terminal:

mvn clean install

java -jar target\JavaSoapToolkit.jar

C# Migration Steps

Add the following service URL as a service reference to your project:

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_N.NNN.wsdl

where

N.NNN

is the latest server API version.

This will generate a Connected Services section in your project. It will also generate an

app.config

file for your project.

Add the following sections to the top of your

app.config

file:

<configuration>
   <configSections>
      <section name="toolkitProperties" type="System.Configuration.NameValueSectionHandler"/>
   </configSections>

   <toolkitProperties>
      <add key="MERCHANT_ID" value="<your_merchant_id>"/>
      <add key="KEY_ALIAS" value="<your_certificate_key_alias>"/>
      <add key="KEY_FILE" value="<your_certificate_file>"/>
      <add key="KEY_PASS" value="<your_certificate_password>"/>
      <add key="KEY_DIRECTORY" value="<path/to/certificate/file>"/>
   </toolkitProperties>
</configuration>

The

<configSections>

tag must be the first section inside

<configurations>

.

In the generated

app.config

file, leave the

<binding>

section as it is.

The

<binding>

section must look like this:

<bindings>
   <basicHttpBinding>
         <binding name="ITransactionProcessor">
         <security mode="Transport"/>
         </binding>
   </basicHttpBinding>
</bindings>

Add this dependency to the

packages.config

file:

<packages>
   <package id="Portable.BouncyCastle" version="1.9.0" targetFramework="net472" />
</packages>

Install the dependency:

nuget install packages.config -OutputDirectory packages

Add this package reference to your

.csproj

file:

<Reference Include="BouncyCastle.Crypto, Version=1.9.0.0, Culture=neutral, PublicKeyToken=0e99375e54769942, processorArchitecture=MSIL">
   <HintPath>packages\Portable.BouncyCastle.1.9.0\lib\net40\BouncyCastle.Crypto.dll</HintPath>
</Reference>

The steps for adding a new dependency can also be done through Visual Studio Package Manager.

Add your P12 certificate to the

KEY_DIRECTORY

.

This

KEY_DIRECTORY

location must be accessible by your code. Ensure that your code has permissions to read this location.

Copy these files to your project directory and import them to your project:

CertificateCacheUtility.cs
InspectorBehavior.cs
PropertiesUtility.cs
SecurityUtility.cs
SoapEnvelopeUtility.cs

Find these lines in your existing code:

TransactionProcessorClient proc = new TransactionProcessorClient();

proc.ChannelFactory.Credentials.UserName.UserName =  request.merchantID;
proc.ChannelFactory.Credentials.UserName.Password =  TRANSACTION_KEY;

ReplyMessage reply = proc.runTransaction(request);

and replace them with these lines:

TransactionProcessorClient proc = new TransactionProcessorClient();

proc.Endpoint.EndpointBehaviors.Add(new InspectorBehavior());

ReplyMessage reply = proc.runTransaction(request);

Find your installation of .NET Framework.

This is often located at

C:\Windows\Microsoft.NET\Framework\v4.0.30319

(32-bit) or

C:\Windows\Microsoft.NET\Framework64\v4.0.30319

(64-bit).

Use

msBuild.exe

to compile your project.

<path_to_framework>\msBuild.exe <name_of_project>.csproj

Run the project executable:

bin\<configuration>\<project_name>.exe

PHP Migration Steps

Update the following service URL (

WSDL_URL

) in your code:

https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_N.NNN.wsdl

where

N.NNN

is the latest server API version.

Copy these files to your project directory:

ExtendedClientWithToken.php
PropertiesUtility.php
SecurityUtility.php

Locate these lines in your existing code:

$soapClient = new ExtendedClient(WSDL_URL, array());

and replace them with these lines:

$soapClient = new ExtendedClientWithToken(
    WSDL_URL,
    array(
        'SSL' => array(
                'KEY_ALIAS' => 'YOUR KEY ALIAS',
                'KEY_FILE' => 'YOUR CERTIFICATE FILE',
                'KEY_PASS' => 'YOUR KEY PASS',
                'KEY_DIRECTORY' => 'PATH TO CERTIFICATES'
            )
        )
);

Update the necessary values for the following fields in your code:

MERCHANT_ID
KEY_ALIAS
KEY_FILE
KEY_PASS
KEY_DIRECTORY

Add your P12 certificate to the

KEY_DIRECTORY

.

This

KEY_DIRECTORY

location must be accessible by your code. Ensure that your code has permissions to read this location.

Run the code:

php <sample_PHP_file>

SSL/TLS Certification Migration