On This Page

Important: Update Payment Message Flow to Use HTTPS Communication

We are moving to industry standard HTTPS communications between merchant systems and . As such, will require all communications between merchant systems and to use HTTPS by April 15, 2025. The SO API endpoints will be updated to accept HTTPS (port 443) data transmissions in January. SCMP API will not be upgraded, and customers will be required update their systems to use either SO or REST.

To facilitate a smooth transition, will provide sample code that can be used as a guide to help with the conversion of the request/response messages in SCMP to the Simple Order scheme. To make this update, customer will need to complete the following changes:

Update HTTP communications to HTTPS communications (from port 80 to port 443).

Enable SO API authentication using P12 certificates.

Enable the SCMP to SO conversion program to run within your payment system.

Click the link below to see the instructions for your language requirements:

Establish HTTPS Communication with Java

The following instructions will provide you with the information you need to transition your payment system to send and receive HTTPS SO API transmissions using Java:

Update HTTP Communications to HTTPS Communications

HTTPS is the standard method for establishing communications between a client and a server.

Updating to HTTPS

To establish HTTPS communication, locate where client/server communication is defined within your system and change it from HTTP to HTTPS. If the port number is set, (for example port 80), change the port to 443.

Before

http://server.com:80

After

https://server.com:443

Enable SO Authentication Using P12 Certificates with Java

As part of ongoing Security Enhancements, we are planning to upgrade SOAP API authentication to P12 authentication. This upgrade is currently available for Java, C#, and PHP.

You can upgrade to P12 Authentication in your SOAP toolkit by doing the following:

Update the files in your project directory.

Add your certificate information to a toolkit.properties file in your project directory.

Update your pom.xml file.

A java tookit is available on GitHub: JavaSoapToolkitCybersource SOAP Toolkit

Prerequisites

You will need an SO P12 Certificate. For Information on creating a P12 certificate, See the Crate a P12 Certificate
.

Your application must meet these requirements:

Java 9 or higher

Jakarta XML Web Services API

JAX-WS Runtime

Jakarta XML Web Services Distribution

Bouncy Castle Cryptography APIs for JDK 1.5 to JDK 1.8

Apache XML Security

WSDL 1.219 or earlier

Java Migration Steps

Follow these steps to upgrade your Java code:

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

You can confirm that your configuration is updated successfully by sending a test request. A successful configuration is indicated when the request log shows that the request was authenticated using a Bearer token.

Enable SCMP to SO Conversions Using Java

This method allows users with an SCMP payment system to maintain that system. The SCMP payloads are converted into an SO payload and sent to the associated SO endpoint. When the SO payload is returned, the payload is then converted back into SCMP for processing by the system. The image below outlines the message path:

An example program is available on GitHub: GitHub Sample Code

Prerequisites

There are no prerequisites for this work.

Establish the SO Payload Conversion

Add the SCMP sample client program to your payment system.

These files can be found in the GitHub resource referenced above.

Update the
cybs.properties
file.

The following list is of values must be updated.

merchantID

: Set this to your production Merchant ID used for commerce.

keysDirectory

: The file path to the P12 certificate generated previously.

password

: The P12 certificate password.

keyAlias

: The name of your MID.

Other values may be set at your discretion. Use the comments within the file to determine which values you wish to change.

After the SCMP payment software creates a request payload, run the
processRequest
method found in the
Util.java
file against that payload.

This method converts the SCMP payload into an SO payload and forwards the SO payload to the correct SO endpoint. When the SO reply payload is received, the method will then convert the payload back into an SCMP payload for normal processing within the system.

Establish HTTPS Communication with .Net

The following instructions will provide you with the information you need to transition your payment system to send and receive HTTPS SO API transmissions using .Net:

Enable SO Authentication Using P12 Certificates with .Net

As part of ongoing Security Enhancements, we are planning to upgrade SOAP API authentication to P12 authentication. This upgrade is currently available for Java, C#, and PHP.

You can upgrade to P12 Authentication in your SOAP toolkit by doing the following:

Update the files in your project directory.

Add your certificate information to a toolkit.properties file in your project directory.

Update your pom.xml file.

A java tookit is available on GitHub: JavaSoapToolkitCybersource SOAP Toolkit

Prerequisites

You will need an SO P12 Certificate. For Information on creating a P12 certificate, See the Crate a P12 Certificate
.

Your application must meet these requirements:

.NET Framework 4.7.2 and later Redistributable Package

NuGet Command-Line Interface

Portable.BouncyCastle

C# Migration Steps

Follow these steps to upgrade your C# code:

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

tag must be the first section inside

In the generated

app.config

file, leave the

section as it is.

The

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

Enable SCMP to SO Conversions Using .Net

An example program is available on GitHub: GitHub Sample Code

Prerequisites

There are no prerequisites for this work.

Establish the SO Payload Conversion

Add the SCMP sample client program to your payment system.

These files can be found in the GitHub resource referenced above.

Update the
app.config
file.

The following list is of values must be updated.

cybs.merchantID

: Set this to your production Merchant ID used for commerce.

cybs.keysDirectory

: The file path to the P12 certificate generated previously.

cybs.password

: The P12 certificate password.

cybs.keyAlias

: The name of your MID.

Other values may be set at your discretion. Use the comments within the file to determine which values you wish to change.

After the SCMP payment software creates a request payload, run the
processRequest
method found in the
Util.cs
file against that payload.