Skip to main content

Switch payment gateways

Zuora

Switch payment gateways

  1. Last updated
  2. Save as PDF

If you currently have a payment gateway for processing transactions in Zuora but want to switch to another new gateway, follow the instructions in this article. In the following sections, the current gateway is referred to as gateway A and the new gateway is referred to as gateway B.

Prerequisites

  • Verify whether gateway B is supported by Zuora’s payment gateway integration service. See Supported payment gateways for more information.
  • Verify whether payment methods, payment operations, and payment processing features that you want are supported by gateway B. See the Overview article for gateway B.
  • Before deactivating gateway A and switching to gateway B, use one of the following approaches to handle possible refunds for existing payments. If gateway A is deactivated, the referenced refunds cannot be processed successfully and an error will return.
    1. Keep gateway A active and continue using it to process referenced refunds for the existing payments.
    2. If gateway B supports non-referenced refunds, create non-referenced refunds with gateway B for the existing payments that were processed through gateway A. You can find whether gateway B supports non-referenced refunds in the Overview article of gateway B.

    If the account and payment method data on gateway A have been migrated to your new merchant account on gateway B, the refund will fail on gateway A even though it is still active. In this case, you must use the option 2.

Procedure

  1. Enable the payment gateway integration for gateway B. See Enable payment gateway integrations for your tenant for more information.
  2. Set up gateway B. See the Set up and configure gateway instance article for payment gateway B.
  3. Update the gateway setting on your tenant depending on your business requirements:
    Business requirements Instructions
    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 gateway B 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 gateway B 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 gateway A in your code, replace it with the gateway ID of gateway B.
    Set gateway B as the default gateway for all customer accounts on your tenant
    1. Follow the instructions in Set up payment gateways to set gateway B as the default gateway.
    2. In Zuora UI, navigate to Customers > Customer Accounts.
    3. Update the payment gateway information for each account by using any of the following methods:
      • Use the CustomerAccounts Zip file. Note that this option is not available to all tenants. If you follow these steps to check and find you do not have this file, use the next method.
        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, and click Export. When the CustomerAccounts.zip file is ready, it is displayed in the list.
        3. Click the file name to download the file.
        4. 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.
        5. Update the CustomerAccount.csv file. For customer accounts that use the default payment gateway, the cell must be empty. Save the file after your editing.
        6. Navigate to Customers > Customer Accounts.
        7. Click the Import icon import customer accounts.
        8. 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.
        9. Click Import.
      • If the CustomerAccounts Zip file is not available, you can follow the instructions in Import customer accounts to download a template, update the template to include the account data. For customer accounts that use the default payment gateway, the cell must be empty. After your editing, save and import the updated file. 
  4. Test the new payment gateway B. See Test payment gateways for more information.
  5. Deactivate the payment gateway A.

Payment method re-authentication after switching to another gateway

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. In instances where gateway A does 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 gateway B, as part of the Stored Credentials Transactions Framework of card networks. You can implement the re-authentication through the pmId client parameter for Payment Pages 2.0. For more information, see the following articles: