Skip to main content

Migrate to CyberSource v2.0

Zuora

Migrate to CyberSource v2.0

  1. Last updated
  2. Save as PDF

Follow the instructions in this article to migrate to the CyberSource, Payment API v2.0 payment gateway integration. In this article, the instances of gateway integrations to be deprecated are referred to as the legacy gateway instance.

Prerequisites

Before deactivating the current legacy gateway instances and switching to CyberSource v2.0, determine your approach to handling refunds for existing payments. After the legacy gateway instance is deactivated, the referenced refunds cannot be processed successfully and an error will return.

Use one of the following approaches to handle possible refunds for existing payments:

Option Description
Use the legacy gateway instance

Keep the legacy gateway instance active and continue using it to process referenced refunds for the existing payments. 

If your p12 key expires, the referenced refunds will fail. In this case, use either of the following workarounds to process the refund for the existing payment:

  • Log in to your CyberSource console and refund the payment, and then create an external refund in Zuora.
  • In Zuora, on the CyberSource v2.0 instance, create non-referenced refunds for the existing payments that were processed through the legacy gateway instance.
Use the CyberSource v2.0 instance On the CyberSource v2.0 instance, create non-referenced refunds for the existing payments that were processed through the legacy gateway instance.

Procedure

To migrate to the CyberSource v2.0 payment gateway integration, complete the following tasks:

  1. Enable the CyberSource, Payment API v2.0 payment gateway integration. See Enable payment gateway integrations for your tenant.
  2. Set up a CyberSource, Payment API v2.0 instance. See Set up and configure a CyberSource payment gateway instance.
  3. Update the gateway setting on your tenant depending on your business requirements:
    Business requirements Instructions
    Set the CyberSource v2.0 instance as the default gateway for all customer accounts on your tenant
    1. Follow the instructions in Set up payment gateways to set the default gateway.
    2. Complete the following steps to check and update the payment gateway setting of customer accounts on your tenant:
      1. In Zuora UI, navigate to Customers > Customer Accounts.
      2. Export customer account data:
        1. On the Accounts page, click the Export icon export customer accounts next to the filter section. The Exports page is displayed.
        2. Select CustomerAccounts Zip from the Export Data dropdown list.
        3. Click Export. When the CustomerAccounts.zip file is ready, it is displayed in the list.
        4. Click the file name to download the file.
        5. Decompress the CustomerAccounts.zip file. It contains three files, including CustomerAccount.csv, Contact.csv, and PaymentMethod.csv. You will only need to use CustomerAccount.csv.
      3. Update the CustomerAccount.csv file. For customer accounts that use the default payment gateway, the cell must be empty.
        1. Open the CustomerAccount.csv file.
        2. For customer accounts that will use the new default payment gateway, update the Payment Gateway cell to empty.
        3. Save the file.
      4. Import the updated CustomerAccount.csv file:
        1. Navigate to Customers > Customer Accounts.
        2. Click the Import icon import customer accounts.
        3. In the Import window, select Customer Accounts from the Type list, and then click Choose File to browse to and select the updated CustomerAccount.csv file.
        4. Click Import.
    Update the gateway setting of a customer account
    1. Open the customer account page.
    2. Navigate to the Billing and Payment Info section, and click Edit.
    3. In the Payment Gateway field, select the CyberSource v2.0 gateway instance from the list.
    4. At the bottom of the section, click Save.
    Update the gateway setting of hosted payment pages
    1. Navigate to Settings > Payments > Setup Payment Page and Payment Link.
    2. Find your payment page in Page List and click Edit in the Action column.
    3. In the Payment Gateway section, select the CyberSource v2.0 gateway instance from the Default Payment Gateway list.
    4. At the bottom of the page, click Generate and Save Page.
    Update customized integration If you have implemented any customized integration by passing in the gateway ID of the legacy gateway instance in your code, replace it with the gateway ID of the CyberSource v2.0 gateway instance.
  4. Deactivate the legacy gateway instance.

Payment method re-authentication after switching to CyberSource v2.0

If you use Zuora Payment Pages 2.0 to host your payment pages, it might be required for cardholders to re-authenticate their payment methods. Because the legacy gateways do not support CIT/MIT, the appropriate parameters might not be stored on file, leading to Authentication Required errors from the issuers. These errors require that the cardholder comes back on-session to re-authenticate by updating an existing card or adding a new one through the CyberSource v2.0 gateway, as part of the Stored Credentials Transactions Framework of card networks. You can implement the re-authentication by using the pmId client parameter for Payment Pages 2.0. For more information, see the following articles: