On This Page

SCMP Mandate Compliance for HTTPS Upgrade Migration Guide

Audience and Purpose

This guide is written for merchants who need to upgrade their SCMP API payment system to send Simple Order API messages to and receive them from
Cybersource
.

Convention

This statement appears in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.

Customer Support

For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.04.01

Retitled guide from
SCMP-to-Simple Order Conversion Migration Guide
 to
SCMP Mandate Compliance for HTTPS Upgrade Migration Guide
.
Added additional details about the security updates and requirements in the introduction. See Introduction to SCMP Mandate Compliance for HTTPS Upgrade.
Added new section explaining how to upgrade the
Cybersource
 Java SCMP Client SDK. See Java SCMP Client SDK Upgrade.

25.03.01

Initial release.

Introduction to SCMP Mandate Compliance for HTTPS Upgrade

The HTTP SCMP endpoints will be decommissioned on April 30th, 2025, as a part of a
Cybersource
 security update, and only these SCMP HTTPS endpoints will be valid:
  • Test:
    ics2test.ic3.com
  • Production:
    ics2.ic3.com
This migration guide explains how to upgrade your SCMP payment system in order to remain compliant with the security update and avoid service disruptions.

Upgrade Methods

Depending on the library you integrated your payment system with, you can complete this upgrade using one of these methods:
  • Java SCMP Client SDK:
     This method only requires you to update the endpoint configuration in your Java SCMP Client SDK to HTTPS. Only the Java SDK version 5.4.0 is valid for this upgrade.
  • Conversion kit for Simple Order API:
     This method uses a conversion kit to upgrade your SCMP payment system to a Simple Order payment system. It is available for C++ and Java programming environments and any application developed using the .NET framework. If your payment system utilizes a language that we do not have a sample reference for,
    Cybersource
     recommends upgrading using the SOAP toolkit or the REST API. For more information about upgrading using the SOAP toolkit, see the
    SOAP Toolkits for Web Services Developer Guide
     and the
    Cybersource
     SOAP Toolkit     in GitHub.
  • REST API:
     If you prefer, you can upgrade your payment system to the REST API instead. For more information about how to upgrade to REST, see the
    Getting Started with REST Developer Guide
    .
    Cybersource
     recommends that you upgrade using this method if possible.

Additional Support

If you have additional questions, please contact your
Cybersource
 account representative for more information, or submit a support ticket here:

C++ Payment System Upgrade

This section describes how to transition your SCMP payment system to send and receive HTTPS Simple Order API transmissions using the C++ programming language. Upgrading your payment system to Simple Order requires you to download an API key from the
Business Center
.

Enable SCMP-to-Simple Order Conversion

The conversion kit method enables users with an SCMP payment system to maintain their SCMP system while using the Simple Order endpoint. When you send an SCMP request to
Cybersource
, the request is converted into a Simple Order request and then sent to the corresponding Simple Order endpoint. When
Cybersource
 returns a Simple Order response, the response is converted into SCMP for your system to process it. This image demonstrates the conversion process:

Figure:

SCMP-to-Simple Order Conversion

Setting Up SCMP-to-Simple Order Conversion

Follow these steps to set up SCMP-to-Simple Order conversion.
  1. Add the SCMP conversion kit to your payment system. Retrieve the conversion kit files from the
    SCMPToNVPTest
     folder in GitHub:
  2. Add the
    cybs.ini
     file to your application. Retrieve the
    cybs.ini
     file from the
    resources
     folder in GitHub:
  3. Update these parameter values in your
    cybs.ini
     file:
    • merchantID
      : Set to your production merchant ID used for commerce.
    • keysDirectory
      : Set to the file path that leads to your P12 certificate.
    • serverURL
      : Set to the
      Cybersource
       Simple Order endpoint.
    • keyFilename
      : Set to the file name of your .p12 file.
    • password
      : Set to your P12 certificate password.
    • sslCertFile
      : Set to the file path and name of your .p12 file.
    merchantID=your-merchant-id
keysDirectory=c:/keys
serverURL=https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/
keyFilename=your-merchant-id.p12
password=test-password
sslCertFile=c:/keys/ics2wstest.ic3.crt
    You can set other files at your discretion. See the comments in the
    README.md
     file to determine which values to change:
  4. After your SCMP payment software creates a request, replace your existing request to SCMP with a request to the
    processRequest
     method from the class in the
    ics_util.cpp
     file. Then, pass your SCMP request as a parameter in the
    processRequest
     method.
    ics_msg* scmpResponse = processRequest(scmpRequest);  // <-- User inputs their SCMP request here
    If you do not have the
    ics_util.cpp
     file, you can retrieve it from the
    SCMPToNVPTest
     folder in GitHub:

Result

When you send an API request to
Cybersource
, the
processRequest
 method converts your SCMP request into a Simple Order request. It then sends the converted request to the correct Simple Order endpoint. When you receive a Simple Order response from
Cybersource
, the response is converted into SCMP for your payment system to process.

Java Payment System Upgrade

Follow these instructions to transition your SCMP payment system to send and receive HTTPS Simple Order API transmissions using the Java programming language. Upgrading your payment system to Simple Order requires you to download an API key from the
Business Center
.
If your system uses the
Cybersource
 Java SDK to send API messages, there is an alternative upgrade method that only requires you to have to update the SCMP endpoint configuration in the SDK. For more information, see Java SCMP Client SDK Upgrade.
You must use Java 8 or later to implement this change.

Enable SCMP-to-Simple Order Conversion

The conversion kit method enables users with an SCMP payment system to maintain their SCMP system while using the Simple Order endpoint. When you send an SCMP request to
Cybersource
, the request is converted into a Simple Order request and then sent to the corresponding Simple Order endpoint. When
Cybersource
 returns a Simple Order response, the response is converted into SCMP for your system to process it. This image demonstrates the conversion process:

Figure:

SCMP-to-Simple Order Conversion

Setting Up SCMP-to-Simple Order Conversion

Follow these steps to set up SCMP-to-Simple Order conversion.
  1. Add the SCMP conversion kit to your payment system. Retrieve the conversion kit files from the
    SCMPSampleClient
     folder in GitHub:
  2. Add the
    cybs.properties
     file to your application. Retrieve the
    cybs.properties
     file from the
    samples/scmp/SCMPSampleClient
     folder in GitHub:
  3. Update these parameter values in your
    cybs.properties
     file:
    • merchantID
      : Set to your production merchant ID used for commerce.
    • keysDirectory
      : Set to the file path that leads to your P12 certificate.
    • keyAlias
      : Set to your merchant ID (MID) name.
    • keyPassword
      : Set to your P12 certificate password.
    • sendToProduction
      : Set to one of these possible values to determine which environment your API request message is sent to:
      • true
        : production environment.
      • false
        : CAS environment.
    merchantID=test_mid
keysDirectory=/user/oliver/keys/
keyAlias=test_mid
keyPassword=test_password
sendToProduction=true
    You can set other files at your discretion. See the comments in the
    README.md
     file to determine which values to change:
  4. After your SCMP payment software creates a request, replace your existing request to SCMP with a request to the
    processRequest
     method from the class in the
    Util.java
     file. Then pass your SCMP request as a parameter in the
    processRequest
     method.
    ICSReply scmpReply = Util.processRequest (scmpRequest, cyberProperties);
    If you do not have the
    Util.java
     file, it is available in the
    samples/scmp/SCMPSampleClient/
    src
     folder in GitHub:

Result

When you send an API request to
Cybersource
, the
processRequest
 method converts your SCMP request into a Simple Order request. It then sends the converted request to the correct Simple Order endpoint. When you receive a Simple Order response from
Cybersource
, the response is converted into SCMP for your payment system to process.

Java SCMP Client SDK Upgrade

Follow these steps to upgrade the endpoint configuration in your Java SCMP Client SDK.
Only the Java SCMP Client SDK version 5.4.0 is valid for this upgrade.
  1. Open your
    ICSClient.props
     file using a text editor application. This file is located in the
    properties
     folder in your Java SDK.
  2. Change the
    serverURL
     property value to one of these valid HTTPS endpoints that corresponds to your environment:
    Test Endpoint
    serverURL=https://ics2test.ic3.com:443/
    Production Endpoint
    serverURL=https://ics2.ic3.com:443/
  3. Add the
    useJdkUrlConnection
     property and set its value to
    true
    .
    useJdkUrlConnection=true
  4. (Optional) Run the authorization sample in the
    ICSAuthTest.java
     file to test and confirm that your HTTPS connection is successful. The file is in the
    samples
     folder.
    In the sample authorization, set the field value in the
    customer_cc_expyr
     field to a future four digit year.

Troubleshooting Using Certificates

If you receive an error message when sending an API request to the HTTPS endpoints, you may need to add certificates to your payment system. Follow these steps to add the Certificate Authority (CA) root certificate and intermediate certificate to your system.
  1. Download the certificates from the attachments section in this support article:
  2. Import the certificates to your Java truststore.
  3. If you need to enable your system to trust the certificates, add these two properties and values to your
    ICSClient.props
     file to override the default Java truststore.
    ssl.trustStore=
    {path_to_your_truststore}
    /keys/truststore.jks
ssl.trustStorePassword=
    {your_password}

.NET Payment System Upgrade

This section describes how to transition your SCMP payment system to send and receive HTTPS Simple Order API transmissions. Upgrading your payment system to Simple Order requires you to download an API key from the
Business Center
.

Enable SCMP-to-Simple Order Conversion

The conversion kit method enables users with an SCMP payment system to maintain their SCMP system while using the Simple Order endpoint. When you send an SCMP request to
Cybersource
, the request is converted into a Simple Order request and then sent to the corresponding Simple Order endpoint. When
Cybersource
 returns a Simple Order response, the response is converted into SCMP for your system to process it. This image demonstrates the conversion process:

Figure:

SCMP-to-Simple Order Conversion

Setting Up SCMP-to-Simple Order Conversion

Follow these steps to set up SCMP-to-Simple Order conversion.
  1. Add the SCMP conversion kit to your payment system. Retrieve the conversion kit files from the
    scmp
     folder in GitHub:
  2. Update these values in your
    app.config
     file. Retrieve the
    app.config
     file from the
    scmp
     folder in GitHub:
    • merchantID
      : Set to your production merchant ID used for commerce.
    • keysDirectory
      : Set to the file path that leads to your P12 certificate.
    • keyAlias
      : Set to your merchant ID (MID) name.
    • password
      : Set to your P12 certificate password.
    <add key="cybs.merchantID" value="" />
<add key="cybs.keysDirectory" value="" />
<add key="cybs.keysAlias" value="" />
<add key="cybs.Password" value="" />
    You can set other files at your discretion. See the comments in the
    README.md
     file to determine which values to change:
  3. After your SCMP payment software creates a request message, run the
    processRequest
     method found in the
    Util.cs
     file against that request.

Result

When you send an API request to
Cybersource
, the
processRequest
 method converts your SCMP request into a Simple Order request. It then sends the converted request to the correct Simple Order endpoint. When you receive a Simple Order response from
Cybersource
, the response is converted into SCMP for your payment system to process.