Release Notes {#rn-general} =========================== These release notes cover all releases to the production server for the week ending December 20, 2024. Announcements {#rn-announce} ============================ The following are important announcements about Cybersource products. Important: Update SCMP Payment Message Flow to Use HTTPS Communication using the SO API {#scmp-so-announcement} =============================================================================================================== Starting in January, Cybersource will enable HTTPS (port 443) communications between payment clients and endpoints. To support the transition to HTTPS communication, the SCMP API users will need to update their system will be updated to accept HTTPS (port 443) data transmissions starting in January. **SCMP Endpoints:** * `http://ics2.ic3.com:80`: HTTP endpoint, will be decommissioned later this year * `https://ics2.ic3.com:443`: HTTPS endpoint, currently available Java Implementations -------------------- The Java SCMP client supports HTTPS. To update your client to use HTTPS, you need to: * Change your communication protocol from HTTP (port 80) to HTTPS (port 443) Non-Java Implementations ------------------------ The C and C++, ASP, .NET, or Perl SCMP clients do not support HTTPS. If you are using one of these clients, you will need to do one of the following: * Rewrite your code to use the Simple Order API using the SO SDK. If you are using C++ or C#, we provide example code to help the transition. * Enable to SCMP to Simple Order Conversion. HTTPS with Java Clients {#scmp-so-java-intro} ============================================= The following instructions will help you to transition your payment system to send and receive HTTPS Simple Order API transmissions using Java: You must use Java 8 or later to implement this change. Update JDK Properties {#java-props-https} ========================================= Update the following properties within the Java SDK: * `serverURL=https://ics2.ic3.com:443/` This tells the SCMP client to use an HTTPS connection. * `useJdkUrlConnection=true` This tells the SCMP client to use the JDK URL Connection. This is required for HTTPS to run. HTTPS with Non-Java Clients {#scmp-so-dotnet-intro} =================================================== The following instructions will help you to transition your payment system to send and receive HTTPS SO API transmissions. Enable SCMP to SO Conversions For Non-Java Clients {#scmp-so-donet-conversion} ============================================================================== This method allows users with an SCMP payment system to maintain the SCMP system while using the SO endpoint. The SCMP payloads are converted into an Simple Order payload and sent to the associated Simple Order endpoint. When the Simple Order payload is returned, the payload is then converted back into SCMP for processing by the system. The image below outlines the message path: ![](/content/dam/new-documentation/documentation/en-us/topics/reference/notes/announcements/2024-10-scmp-so/images/SCMPtoSO.svg/jcr:content/renditions/original) > An example program for C++, .NET, and PHP are available on GitHub: [GitHub Sample Code](https://github.com/CyberSource#simple-order-soap-api-related-products "") Prerequisites ------------- There are no prerequisites for this work. Establish the Simple Order Payload Conversion --------------------------------------------- 1. Add the SCMP sample client program to your payment system. These files can be found in the GitHub resource referenced above. 2. Update the `app.config` 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. 3. After the SCMP payment software creates a request payload, run the `processRequest` method found in the `Util.cs` file against that payload. This method converts the SCMP payload into an Simple Order payload and forwards the Simple Order payload to the correct Simple Order endpoint. When the Simple Order reply payload is received, the method will then convert the payload back into an SCMP payload for normal processing within the system. Important: SOAP Toolkit Update {#rn-so-p12} =========================================== 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: * Create a P12 certificate. * 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. {#rn-so-p12_ul_iw5_35v_ldc} You must upgrade the SOAP authentication to use P12 by these dates. **Test**: April 14, 2025 **Production**: May 13, 2025 > This update is currently available only for the C#, Java, and PHP SOAP Toolkit. The updated SDK is available here on GitHub: > * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "") > * [Java SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/JavaSoapToolkit "") > * [PHP SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/PHPSoapToolkit "") > {#rn-so-p12_ul_kcw_3cz_mdc} > Other toolkits will be available in January 2025. > This Java SOAP Toolkit update works only with [WSDL](https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.219.wsdl "") or [XSD](https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.219.xsd "") 1.219 or earlier. Available Environments ---------------------- This update is available in these environments: * **Test**: https://apitest.cybersource.com * **Production**: https://api.cybersource.com Java Prerequisites ------------------ You must create a P12 certificate. See the *[Getting Started with REST Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro/restgs-security-p12-intro.md "")*. With this change to use a P12 certificate in your Java SOAP toolkit configuration, your application must meet these new 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 C# Prerequisites ---------------- You must create a P12 certificate. See the *[Getting Started with REST Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro/restgs-security-p12-intro.md "")*. With this change to use a P12 certificate in your C# SOAP toolkit configuration, your application must meet these new requirements: * .NET Framework 4.7.2 and later Redistributable Package * [NuGet Command-Line Interface](https://learn.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference?tabs=windows "") * Portable.BouncyCastle {#rn-so-p12_ul_nqh_t5v_ldc} PHP Prerequisites ----------------- You must create a P12 certificate. See the *[REST Getting Started Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro/restgs-security-p12-intro.md "")*. With this change to use a P12 certificate in your PHP SOAP toolkit configuration, the new requirements for your application will be: * PHP 5.6x and higher * PHP SOAP extension * PHP OpenSSL extension {#rn-so-p12_ul_gpv_mcz_mdc} 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 ``` 10. (Optional) You can confirm that your configuration is updated successfully by checking that your request was authenticated using a Bearer token. To confirm, add this command after line 54 in the **src\\main\\java\\com\\cybersource\\BinarySecurityTokenHandler.java** file: ``` System.out.println( soapMessageContext ); ``` C# Migration Steps ------------------ Follow these steps to upgrade your C# code: 1. 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. 2. 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> `. 3. 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> ``` 3. Add this dependency to the `packages.config` file: ``` <packages> <package id="Portable.BouncyCastle" version="1.9.0" targetFramework="net472" /> </packages> ``` 4. Install the dependency: ``` nuget install packages.config -OutputDirectory packages ``` 5. 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. 6. 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. 7. Copy these files to your project directory and import them to your project: * [CertificateCacheUtility.cs](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/CSharpSoapToolkit/CSharpSoapToolkit%5CCertificateCacheUtility.cs "") * [InspectorBehavior.cs](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/CSharpSoapToolkit/CSharpSoapToolkit%5CInspectorBehavior.cs "") * [PropertiesUtility.cs](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/CSharpSoapToolkit/CSharpSoapToolkit%5CPropertiesUtility.cs "") * [SecurityUtility.cs](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/CSharpSoapToolkit/CSharpSoapToolkit%5CSecurityUtility.cs "") * [SoapEnvelopeUtility.cs](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/CSharpSoapToolkit/CSharpSoapToolkit%5CSoapEnvelopeUtility.cs "") {#rn-so-p12_ul_ypc_v5v_ldc} 8. 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); ``` 9. 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). 10. Use `msBuild.exe` to compile your project. ``` <path_to_framework>\msBuild.exe <name_of_project>.csproj ``` 11. Run the project executable: ``` bin\<configuration>\<project_name>.exe ``` 12. (Optional) You can confirm that your configuration is updated successfully by checking that your request was authenticated using a Bearer token. To confirm, add this command after line 59 in the **CSharpSoapToolkit\\InspectorBehavior.cs** file: ``` Console.WriteLine(request.ToString()); ``` {#rn-so-p12_ol_xpc_v5v_ldc} PHP Migration Steps ------------------- Follow these steps to upgrade your existing PHP code: 1. 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. 2. Copy these files to your project directory: * [ExtendedClientWithToken.php](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/PHPSoapToolkit/ExtendedClientWithToken.php "") * [PropertiesUtility.php](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/PHPSoapToolkit/PropertiesUtility.php "") * [SecurityUtility.php](https://github.com/CyberSource/cybersource-soap-toolkit/blob/master/PHPSoapToolkit/SecurityUtility.php "") {#rn-so-p12_ul_rcp_rcz_mdc} 3. 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' ) ) ); ``` 4. Update the necessary values for the following fields in your code: * `MERCHANT_ID` * `KEY_ALIAS` * `KEY_FILE` * `KEY_PASS` * `KEY_DIRECTORY` {#rn-so-p12_ul_scp_rcz_mdc} 5. 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. 6. Run the code: ``` php <sample_PHP_file> ``` 7. (Optional) You can confirm that your configuration is updated successfully by checking that your request was authenticated using a Bearer token. To confirm, add this command after line 109 in the **ExtendedClientWithToken.php** file: ``` print_r($request); ``` {#rn-so-p12_ol_qcp_rcz_mdc} \>SSL/TLS Certification Migration {#announcement-tls} ======================================================== To uphold the maximum levels of security and compliance in both your browser-based and server-to-server interactions with the Visa Acceptance Solutions platform (including Cybersource), we are transitioning all Cybersource endpoint SSL/TLS certificates from Entrust to DigiCert. These SSL/TLS certificates, originally issued by Entrust, will now be issued by DigiCert to fortify these communication channels. Merchants using Cybersource endpoints should coordinate with their network team or hosting/solution provider to implement all necessary measures to ensure their connections to Cybersource properties follow industry standards. This includes updating their systems with the new Root and Intermediate (CA) SSL/TLS certificates that correspond to the specific Cybersource endpoint they use. If your application requires trusting of certificates at the server level, you must install (trust) the new certificates prior to expiration of existing certificates to avoid any production impact. The link to the Server-Level (leaf) SSL certificate will be updated when they become available. We recommended that merchants trust only the Root and Intermediate CA SSL/TLS certificates on all secure endpoints. This method avoids the annual necessity to renew the server-level certificate. Do not revoke or remove any of your existing Entrust certificates linked with Cybersource endpoints before the scheduled dates. Until the cut-off dates, the only supported certificates will be the Entrust SSL certificates. You may add the new certificates to your system, in addition to the existing certificates, and verify their functionality in the testing environment. There will be two phases and each phase will update different endpoints. **First Phase** The first phase is complete and updated the following endpoints: | Test URLs | Production URLs | |----------------------------------------|------------------------------------| | apitest.cybersource.com | accountupdater.cybersource.com | | accountupdatertest.cybersource.com | api.cybersource.com | | batchtest.cybersource.com | batch.cybersource.com | | api.accountupdatertest.cybersource.com | api.accountupdater.cybersource.com | | ics2wstest.ic3.com | ics2ws.ic3.com | | ics2wstesta.ic3.com | ics2wsa.ic3.com | | apitest.cybersource.com | ics2ws.in.ic3.com | | | api.in.cybersource.com | | | batch.in.cybersource.com | [The new certificates can be found in the zip file at this link.](https://support.visaacceptance.com/_entity/annotation/466529d7-9143-ef11-8409-000d3a379023 "") We strongly urge you to test your implementation as soon as possible. **Second Phase** The second phase will update the following endpoints: | Test URLs | Production URLs | |--------------------------------------|-------------------------------------| | testflex.cybersource.com | flex.cybersource.com | | testsecureacceptance.cybersource.com | secureacceptance.cybersource.com | | | flex.in.cybersource.com | | | secureacceptance.in.cybersource.com | The Testing Environment was updated November 5, 2024, 4:00 GMT. The production environment was updated December 10, 2024, 4:00 GMT. The old certifications will expire on December 31, 2024. Features Introduced This Week {#rn-features} ============================================ RM-33297 -------- Description : This release enhances Microform v2 to be PCI DSS 4.0 compliant. Microform now returns an SRI Value (Sub-resource Integrity) to the merchant to validate the legitimacy of the JavaScript being loaded on their page. Audience : Users of Microform v2. Benefit : The Payment Card Industry Data Security Standard (PCI DSS) ensures that payment information is protected. Technical Details : None. Important Dates : Released to production December 16. Salesforce For Commerce 24.1.2 ------------------------------ Description : This release adds P12 authentication to comply with a security mandate. Audience : Users of Salesforce For Commerce 24.1.2. Benefit : Improved security. Technical Details : None. Important Dates : Released December 20. **Commercetools 24.3.1** ------------------------ Description : This release enables merchants to use merchant-defined metadata. : Users will also receive a connection status message when they open the app. Audience : Resellers. Benefit : Merchant-defined metadata can be used for reporting, analytics, or other purposes as the merchant sees fit. Technical Details : On the client side, pass the metadata object as a string in the **ISV_metadata** payment customer field of Commercetools. The plugin will pass the value to the merchantDefinedInformation API field of the Cybersource Authorization and Order Management service. The passed values can be verified in the Merchant Defined Data section of the transaction details in the Business Center. Important Dates : Released December 20. Fixed Issues {#rn-fixed-issues} =============================== No customer-facing fixes were released this week. Known Issues {#rn-known-issues} =============================== **Reporting** \| 1542583 ------------------------ Description : When digital payment transactions use the Cybersource decryption method and fail with the error *102 DINVALIDDATA Unable to Decrypt Payment Data*, the error is not displayed in reports. This might cause difficulties in identifying the root cause of those rejections during reconciliation. Audience : Merchants and resellers using digital payment transactions that use the Cybersource decryption method. Technical Details : None. Workaround : None. **Decision Manager** \| 1621465 ------------------------------- Description : Transactions processed through the Elavon Americas gateway that combine Decision Manager and payment authorization with CVV are being declined. Audience : Merchants who process Decision Manager transactions and use Elavon Americas. Technical Details : Error Message: *Reason Code 102*. : Reply Message: *The following request field(s) is either invalid or missing: card_suffix*. Workaround : None. **Apple Pay** \| 1619722 ------------------------ Description : When an Apple Pay refund is submitted for an authorization that is more than 60 days old and the refund uses a two-digit expiration date, the refund is declined. Audience : Merchants who process Apple Pay refunds. Technical Details : Error Message: *The field is invalid: paymentInstrument.card.expirationYear*. Workaround : Send four-digit expiration date. **Payments** \| 1600780 ----------------------- Description : A defect is affecting authorization reversal responses in the Business Center. When a user in the Business Center initiates an authorization reversal for a transaction that was successfully authorized, the wrong authorization amount is returned in the response. Audience : Users that process transactions in the Business Center. Technical Details : The user receives this response code: *RC 102 There is a problem processing this request: Auth reversal amount does not match auth amount*. Workaround : None. The authorization, if not captured, will expire in the issuer's system. **Decision Manager** -------------------- Description : Users who do not have administrator permissions in the Business Center may be unable to see some negative list hyperlinks under Decision Manager \> Case Management \> Model Results, and in Transaction Management \> Transaction \> Transaction Details. Audience : Merchants using Decision Manager to review orders. Technical Details : None. Workaround : None. **Merchant Boarding** \| 1614572 -------------------------------- Description : Some users of the VAP Portfolio might be able to set up new gateways for existing merchant accounts, which can cause transaction failure. Audience : Merchants who use the Business Center's Merchant Management feature to configure Merchant accounts using the Card Processing template. Technical Details : If a user who does not have **Template Edit** permission edits the card processing configuration of an existing Merchant ID by adding a new gateway, our internal gateway selector might not send transactions to the expected gateway. Workaround : Ensure that Template Edit permission is given to all users who configure merchant accounts in the Business Center. API Response Codes \| 1561217 ----------------------------- Description : A defect is causing transactions for pre-paid non-reloadable cards that are approved by Worldpay to be declined by our system due to invalid response code mapping. Audience : Merchants who process transactions for pre-paid non-reloadable cards using Worldpay. Technical Details : None. Workaround : None.