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 any other 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 at gateway A side have been migrated to your new merchant account for 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. If you want to set gateway B as the default gateway, see the instructions in Set up payment gateways.
  4. If you set gateway B as your new default gateway, complete the following steps to check and update the payment gateway setting of the 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 filer section. The Exports page is displayed and CustomerAccounts Zip is pre-populated in the Export Data field.
      2. On the Exports page, 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 CustomerAcount.csv, Contact.csv, and PaymentMethod.csv. You will only need to use CustomerAcount.csv.
    3. Update the CustomerAcount.csv file. For customer accounts that use the default payment gateway, the cell must be empty.
      1. Open the CustomerAcount.csv file.
      2. For customer accounts that will use the new default payment gateway (gateway B), update the Payment Gateway cell to empty.
      3. Save the file.
    4. Import the updated CustomerAcount.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 CustomerAcount.csv file.
      4. Click Import.
  5. Test the new payment gateway B. See Test payment gateways for more information.
  6. Deactivate the old payment gateway A.

Payment method re-authentication after switching to another gateway

If you use Zuora Payment Pages 2.0 to host your payment method pages and you want to switch to another payment gateway after the stored credential profile has been created for a payment method, you must require your end customer to re-authenticate the payment method on the hosted payment page. You can implement the re-authentication through the pmId client parameter for Payment Pages 2.0. For more information, see the following articles: