On This Page

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 .
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:
  1. 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>
  2. 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>
  3. 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.
  4. Run this command in your terminal:
    mvn clean jaxws:wsimport
  5. 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();
  6. Copy these files to your project directory:
    • BinarySecurityTokenHandler.java
    • PropertiesUtil.java
    • SecurityUtil.java
  7. 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.
  8. Add your P12 certificate to your key directory.
  9. 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.