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}