Release Notes {#rn-general}
===========================

These release notes cover all releases to the production server for the week ending January 17, 2025.

Announcements {#rn-announce}
============================

Important: SOAP Toolkit Update
------------------------------

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#, 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-announce_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 Java, PHP, C++, and C# SOAP Toolkits. The updated SDK is available here on GitHub:
> * [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 "")
> * [C++ SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CPlusPlusSoapToolkit "")
> * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "")
>   {#rn-announce_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://apitest.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-announce_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-announce_ul_gpv_mcz_mdc}

C++ 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 C++ SOAP toolkit configuration, the new requirements for your application will be:
* GSOAP 2.8.135 or higher (developer version including header files)
* OpenSSL 3.4.0 or higher (developer version including header files)
* G++ compiler
  {#rn-announce_ul_bqs_gdp_zdc}

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 latest 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 to your code. Ensure that your code has permission 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-announce_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);
   ```

   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 one of these locations:

   * *C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319* (32-bit)
   * *C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319* (64-bit)
     {#rn-announce_ul_gtq_zdp_zdc}
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-announce_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
   ```

   *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-announce_ul_rcp_rcz_mdc}
3. FInd these lines in your existing code:

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

   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 these fields in your code:

   * MERCHANT_ID
   * KEY_ALIAS
   * KEY_FILE
   * KEY_PASS
   * KEY_DIRECTORY
     {#rn-announce_ul_scp_rcz_mdc}
5. Add your P12 certificate to the KEY_DIRECTORY.  
   This KEY_DIRECTORY location must be accessible to your code. Ensure that your code has permission to read this location.

6. Run the code:

   ```
   php <sample_PHP_file>
   ```
7. (Optional) You can confirm that your configuration is updated successfully by confirming 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-announce_ol_qcp_rcz_mdc}

C++ Migration Steps
-------------------

Follow these steps to upgrade your existing C++ code:

1. Update your existing Makefile.  
   Change the `cybsdemo` target from:

   ```
   cybsdemo:     sample.cpp $(SOAPH) $(SOAPCPP) ../gsoap/dom.cpp wsseapi.o smdevp.o
   		$(CPP) $(CFLAGS) -o cybsdemo sample.cpp soapC.cpp soapClient.cpp ../gsoap/dom.cpp $(SOAPCPP) wsseapi.o smdevp.o $(LIBS)
   ```

   To:

   ```
   cybsdemo:	sample.cpp $(SOAPH) $(SOAPCPP) ../gsoap/dom.cpp wsseapi.o smdevp.o
   		$(CPP) $(CFLAGS) -o cybsdemo sample.cpp soapC.cpp ../gsoap/dom.cpp stdsoap2.cpp ../gsoap/import/custom/struct_timeval.cpp ../gsoap/plugin/threads.c ../gsoap/plugin/mecevp.c ../gsoap/plugin/wsaapi.c wsseapi.o smdevp.o soapITransactionProcessorProxy.cpp ../gsoap/import/gsoapWinInet.cpp PropertiesUtil.cpp BinarySecurityTokenHandler.cpp $(LIBS)
   ```

   If you do not have an existing Makefile, you can use one of the following Makefiles:

   * [UnixBuildAllCommented.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/UnixBuildAllCommented.Makefile "")
   * [UnixQuickBuild.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/UnixQuickBuild.Makefile "")
   * [WindowsBuildAllCommented.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/WindowsBuildAllCommented.Makefile "")
   * [WindowsQuickBuild.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/WindowsQuickBuild.Makefile "")
     {#rn-announce_ul_z3n_jdp_zdc}  
     `Cybersource` recommends that you use UnixBuildAllCommented.Makefile or WindowsBuildAllCommented.Makefile. If you need to make changes to individual targets, `Cybersource` recommends that you use UnixQuickBuild.Makefile or WindowsQuickBuild.Makefile, as each target can be built individually.
2. CyberSourceTransaction WSDL and XSD version 1.224 are available here:

   * [CyberSourceTransaction_1.224.wsdl](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/CyberSourceTransaction_1.224.wsdl "")
   * [CyberSourceTransaction_1.224.xsd](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/CyberSourceTransaction_1.224.xsd "")

   {#rn-announce_ul_ajn_jdp_zdc}  
   If you want to use a different version, download your preferred version to the project directory and update the versions in the `header` target of your makefile. For example, change:

   ```
   header:	CyberSourceTransaction_1.224.wsdl
   		$(GWSDL) -t ../gsoap/WS/WS-typemap.dat -s -o cybersource.h CyberSourceTransaction_1.224.wsdl
   ```

   to:

   ```
   header:	CyberSourceTransaction_1.219.wsdl
   		$(GWSDL) -t ../gsoap/WS/WS-typemap.dat -s -o cybersource.h CyberSourceTransaction_1.219.wsdl
   ```
3. Add gsoap to the compile path. You can do this by using one of these methods:

   * Copy the gsoap directory, including the header files, to one level above the project directory.
   * Update all paths in the Makefile that reference 'gsoap' to point to where gsoap is located.
     {#rn-announce_ul_bjn_jdp_zdc}
4. Update your sample.cpp file to match your test credentials:

   ```
   const char *MERCHANT_ID = "your_merchant_id";
   const char *TRANSACTION_KEY = "your_transaction_key";
   ```

   If you do not have an existing sample.cpp file, you can use the version that is provided here: [sample.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/sample.cpp "").  
   If you are using an existing sample.cpp file from a previous C++ SOAP Toolkit, you must refer to all "upgrading from previous versions" comments throughout [sample.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/sample.cpp "") to see what has changed.

5. Include these new source files in your project:
   *

   * [BinarySecurityTokenHandler.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/BinarySecurityTokenHandler.cpp "")
   * [BinarySecurityTokenHandler.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/BinarySecurityTokenHandler.h "")
   * [PropertiesUtil.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/PropertiesUtil.cpp "")
   * [PropertiesUtil.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/PropertiesUtil.h "")
   * [stdsoap2.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/stdsoap2.cpp "")
   * [stdsoap2.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/stdsoap2.h "")
     {#rn-announce_ul_djn_jdp_zdc}
     {#rn-announce_ul_cjn_jdp_zdc}
6. Edit the toolkit.properties configuration file to match your test credentials:

   ```
   MERCHANT_ID= 
   KEY_ALIAS= 
   KEY_FILE= 
   KEY_PASS= 
   KEY_DIRECTORY=
   ```

   The toolkit.properties configuration file is read from the same location as the executable at run time.

   > You must make sure that there are no spaces at the start and end of the lines, or either side of ` = `.

7. Run this command in your terminal:

   ```
   make header
   ```

   This generates the cybersource.h file.

8. Insert this text in the Import section of cybersource.h:

   ```
   #import "WS-Header.h"
   ```
9. Run this command in your terminal:

   ```
   make source
   ```

   This generates these files:

   * soapITransactionProcessorProxy.cpp
   * soapITransactionProcessorProxy.h
   * ITransactionProcessor.runTransaction.req.xml
   * ITransactionProcessor.runTransaction.res.xml
   * ITransactionProcessor.nsmap
   * soapStub.h
   * soapH.h
   * soapC.cpp
     {#rn-announce_ul_ejn_jdp_zdc}
10. Run these commands in your terminal:

    ```
    make wsseapi.o
    make smdevp.o
    make cybsdemo 
    ```

    This generates the cybsdemo.exe executable.

11. Add your P12 certificate to the `KEY_DIRECTORY`.

12. Run the cybsdemo.exe executable in your terminal.  
    A successful console output consists of the `keyFile` full path, followed by the response from the web service and no errors. For example:

    ```
    keyFile full path: C:/keys/test_p12_file.p12
    decision = APPROVED
    reasonCode = 0
    requestID = 6017349752184504643266
    requestToken = Axxd6DCgJoj77wSTjm5pe7DwFPfjpNDMyadDIZ/u1Pfje7D9IGU1ogwAGkmXoDc3JoZmTToZDIAAvxSz
    ccAuthReply.reasonCode = 0
    ```

{#rn-announce_ol_y3n_jdp_zdc}

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-non-java-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-non-java-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/scmp-to-so.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 for Java Users {#so-p12-java-intro}
==================================================================

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#, 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.
  {#so-p12-java-intro_d7e20}  
  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 Java, PHP, C++, and C# SOAP Toolkits. The updated SDK is available here on GitHub:
> * [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 "")
> * [C++ SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CPlusPlusSoapToolkit "")
> * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "")
>   {#so-p12-java-intro_d7e61}
>   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://apitest.cybersource.com

Java {#rn-announce}
===================

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

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 latest 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 ); 
    ```

Important: SOAP Toolkit Update for C++ Users {#so-p12-c-plus-intro}
===================================================================

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#, 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.
  {#so-p12-c-plus-intro_d7e20}  
  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 Java, PHP, C++, and C# SOAP Toolkits. The updated SDK is available here on GitHub:
> * [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 "")
> * [C++ SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CPlusPlusSoapToolkit "")
> * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "")
>   {#so-p12-c-plus-intro_d7e61}
>   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://apitest.cybersource.com

C++ {#rn-announce}
==================

C++ 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 C++ SOAP toolkit configuration, the new requirements for your application will be:
* GSOAP 2.8.135 or higher (developer version including header files)
* OpenSSL 3.4.0 or higher (developer version including header files)
* G++ compiler
  {#rn-announce_ul_bqs_gdp_zdc}

Migration Steps
---------------

Follow these steps to upgrade your existing C++ code:

1. Update your existing Makefile.  
   Change the `cybsdemo` target from:

   ```
   cybsdemo:     sample.cpp $(SOAPH) $(SOAPCPP) ../gsoap/dom.cpp wsseapi.o smdevp.o
   		$(CPP) $(CFLAGS) -o cybsdemo sample.cpp soapC.cpp soapClient.cpp ../gsoap/dom.cpp $(SOAPCPP) wsseapi.o smdevp.o $(LIBS)
   ```

   To:

   ```
   cybsdemo:	sample.cpp $(SOAPH) $(SOAPCPP) ../gsoap/dom.cpp wsseapi.o smdevp.o
   		$(CPP) $(CFLAGS) -o cybsdemo sample.cpp soapC.cpp ../gsoap/dom.cpp stdsoap2.cpp ../gsoap/import/custom/struct_timeval.cpp ../gsoap/plugin/threads.c ../gsoap/plugin/mecevp.c ../gsoap/plugin/wsaapi.c wsseapi.o smdevp.o soapITransactionProcessorProxy.cpp ../gsoap/import/gsoapWinInet.cpp PropertiesUtil.cpp BinarySecurityTokenHandler.cpp $(LIBS)
   ```

   If you do not have an existing Makefile, you can use one of the following Makefiles:

   * [UnixBuildAllCommented.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/UnixBuildAllCommented.Makefile "")
   * [UnixQuickBuild.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/UnixQuickBuild.Makefile "")
   * [WindowsBuildAllCommented.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/WindowsBuildAllCommented.Makefile "")
   * [WindowsQuickBuild.Makefile](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/WindowsQuickBuild.Makefile "")
     {#rn-announce_ul_z3n_jdp_zdc}  
     `Cybersource` recommends that you use UnixBuildAllCommented.Makefile or WindowsBuildAllCommented.Makefile. If you need to make changes to individual targets, `Cybersource` recommends that you use UnixQuickBuild.Makefile or WindowsQuickBuild.Makefile, as each target can be built individually.
2. CyberSourceTransaction WSDL and XSD version 1.224 are available here:

   * [CyberSourceTransaction_1.224.wsdl](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/CyberSourceTransaction_1.224.wsdl "")
   * [CyberSourceTransaction_1.224.xsd](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/CyberSourceTransaction_1.224.xsd "")

   {#rn-announce_ul_ajn_jdp_zdc}  
   If you want to use a different version, download your preferred version to the project directory and update the versions in the `header` target of your makefile. For example, change:

   ```
   header:	CyberSourceTransaction_1.224.wsdl
   		$(GWSDL) -t ../gsoap/WS/WS-typemap.dat -s -o cybersource.h CyberSourceTransaction_1.224.wsdl
   ```

   to:

   ```
   header:	CyberSourceTransaction_1.219.wsdl
   		$(GWSDL) -t ../gsoap/WS/WS-typemap.dat -s -o cybersource.h CyberSourceTransaction_1.219.wsdl
   ```
3. Add gsoap to the compile path. You can do this by using one of these methods:

   * Copy the gsoap directory, including the header files, to one level above the project directory.
   * Update all paths in the Makefile that reference 'gsoap' to point to where gsoap is located.
     {#rn-announce_ul_bjn_jdp_zdc}
4. Update your sample.cpp file to match your test credentials:

   ```
   const char *MERCHANT_ID = "your_merchant_id";
   const char *TRANSACTION_KEY = "your_transaction_key";
   ```

   If you do not have an existing sample.cpp file, you can use the version that is provided here: [sample.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/sample.cpp "").  
   If you are using an existing sample.cpp file from a previous C++ SOAP Toolkit, you must refer to all "upgrading from previous versions" comments throughout [sample.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/sample.cpp "") to see what has changed.

5. Include these new source files in your project:
   *

   * [BinarySecurityTokenHandler.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/BinarySecurityTokenHandler.cpp "")
   * [BinarySecurityTokenHandler.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/BinarySecurityTokenHandler.h "")
   * [PropertiesUtil.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/PropertiesUtil.cpp "")
   * [PropertiesUtil.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/PropertiesUtil.h "")
   * [stdsoap2.cpp](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/stdsoap2.cpp "")
   * [stdsoap2.h](https://github.com/CyberSource/cybersource-soap-toolkit/blob/p12auth/CPlusPlusSoapToolkit/stdsoap2.h "")
     {#rn-announce_ul_djn_jdp_zdc}
     {#rn-announce_ul_cjn_jdp_zdc}
6. Edit the toolkit.properties configuration file to match your test credentials:

   ```
   MERCHANT_ID= 
   KEY_ALIAS= 
   KEY_FILE= 
   KEY_PASS= 
   KEY_DIRECTORY=
   ```

   The toolkit.properties configuration file is read from the same location as the executable at run time.

   > You must make sure that there are no spaces at the start and end of the lines, or either side of ` = `.

7. Run this command in your terminal:

   ```
   make header
   ```

   This generates the cybersource.h file.

8. Insert this text in the Import section of cybersource.h:

   ```
   #import "WS-Header.h"
   ```
9. Run this command in your terminal:

   ```
   make source
   ```

   This generates these files:

   * soapITransactionProcessorProxy.cpp
   * soapITransactionProcessorProxy.h
   * ITransactionProcessor.runTransaction.req.xml
   * ITransactionProcessor.runTransaction.res.xml
   * ITransactionProcessor.nsmap
   * soapStub.h
   * soapH.h
   * soapC.cpp
     {#rn-announce_ul_ejn_jdp_zdc}
10. Run these commands in your terminal:

    ```
    make wsseapi.o
    make smdevp.o
    make cybsdemo 
    ```

    This generates the cybsdemo.exe executable.

11. Add your P12 certificate to the `KEY_DIRECTORY`.

12. Run the cybsdemo.exe executable in your terminal.  
    A successful console output consists of the `keyFile` full path, followed by the response from the web service and no errors. For example:

    ```
    keyFile full path: C:/keys/test_p12_file.p12
    decision = APPROVED
    reasonCode = 0
    requestID = 6017349752184504643266
    requestToken = Axxd6DCgJoj77wSTjm5pe7DwFPfjpNDMyadDIZ/u1Pfje7D9IGU1ogwAGkmXoDc3JoZmTToZDIAAvxSz
    ccAuthReply.reasonCode = 0
    ```

{#rn-announce_ol_y3n_jdp_zdc}

Important: SOAP Toolkit Update for C# Users {#so-p12-c-sharp-intro}
===================================================================

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#, 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.
  {#so-p12-c-sharp-intro_d7e20}  
  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 Java, PHP, C++, and C# SOAP Toolkits. The updated SDK is available here on GitHub:
> * [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 "")
> * [C++ SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CPlusPlusSoapToolkit "")
> * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "")
>   {#so-p12-c-sharp-intro_d7e61}
>   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://apitest.cybersource.com

C# {#rn-announce}
=================

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-announce_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-announce_ul_gpv_mcz_mdc}

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 to your code. Ensure that your code has permission 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-announce_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);
   ```

   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 one of these locations:

   * *C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319* (32-bit)
   * *C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319* (64-bit)
     {#rn-announce_ul_gtq_zdp_zdc}
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-announce_ol_xpc_v5v_ldc}

Important: SOAP Toolkit Update for PHP Users {#so-p12-php-intro}
================================================================

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#, 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.
  {#so-p12-php-intro_d7e20}  
  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 Java, PHP, C++, and C# SOAP Toolkits. The updated SDK is available here on GitHub:
> * [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 "")
> * [C++ SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CPlusPlusSoapToolkit "")
> * [C# SOAP toolkit](https://github.com/CyberSource/cybersource-soap-toolkit/tree/master/CSharpSoapToolkit "")
>   {#so-p12-php-intro_d7e61}
>   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://apitest.cybersource.com

PHP {#rn-announce}
==================

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-announce_ul_gpv_mcz_mdc}

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
   ```

   *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-announce_ul_rcp_rcz_mdc}
3. FInd these lines in your existing code:

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

   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 these fields in your code:

   * MERCHANT_ID
   * KEY_ALIAS
   * KEY_FILE
   * KEY_PASS
   * KEY_DIRECTORY
     {#rn-announce_ul_scp_rcz_mdc}
5. Add your P12 certificate to the KEY_DIRECTORY.  
   This KEY_DIRECTORY location must be accessible to your code. Ensure that your code has permission to read this location.

6. Run the code:

   ```
   php <sample_PHP_file>
   ```
7. (Optional) You can confirm that your configuration is updated successfully by confirming 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-announce_ol_qcp_rcz_mdc}

Features Introduced This Week {#rn-features}
============================================

No customer-facing features were released this week.

Fixed Issues {#rn-fixed-issues}
===============================

No customer-facing fixes were released this week.

Known Issues {#rn-known-issues}
===============================

Reporting \| RITM18309968
-------------------------

Description
:
An intermittent issue can cause the Purchase and Refund report to display duplicate rows.

Audience
:
Merchants who use the Purchase and Refund report.

Technical Details
:
None.

Workaround
:
None.

Payments \| 1694196
-------------------

Description
:
Due to an intermittent issue, credit authorizations (online credit) might be processed as standard credits (offline credit). This issue can affect compliance in some mandated regions.

Audience
:
Merchants who use credit authorizations to refund customers.

Technical Details
:
None.

Workaround
:
None.

Payments \| RITM18769444
------------------------

Description
:
Due to an intermittent issue, when merchants on the GetNet gateway cancel a credit using the Cancel Transaction API, an internal error sometimes occurs.

Audience
:
Users of the Cancel Transaction API on the GetNet gateway.

Technical Details
:
None.

Workaround
:
None.

Fraud Management Essentials \| 1672469
--------------------------------------

Description
:
Search results for Fraud Managerment Essentials in the Business Center are currently prevented from being exported.

Audience
:
Users of Fraud Management Essentials.

Technical Details
:
None.

Workaround
:
Try using the Reporting feature or copy and paste from the user interface.

Custom Roles on VAP \| 1641831
------------------------------

Description
:
When a reseller account uses the Visa Analytics Platform (VAP) to create a custom role for a merchant-level user, the role is not applied, and the user does not inherit the permissions for the custom role.

Audience
:
Users of VAP who use custom roles.

Technical Details
:
None.

Workaround
:
To add the custom role:

    1. Navigate to the newly created account's user profile.
    2. From the User Role drop-down menu, select CUSTOM.
    3. Create the custom role.

{#rn-known-issues_ul_rtj_pdj_xdc}