Skip to main content

Set Up Payment Gateways


Set Up Payment Gateways

Each payment gateway has its own requirements. Every gateway must be configured individually.

If you are using multiple payment gateways, you must configure a separate gateway profile for each merchant ID you want to use.

Zuora recommends having the required gateway information before you start configuration.

Enable payment gateway integrations for your tenant

Before you set up and configure a payment gateway instance for your tenant, the payment gateway integration must be enabled on your tenant. You can enable the maximum number of gateway integration types that you are entitled to.

Complete the following steps to enable payment gateway integrations:

  1. Click your username in the upper right and navigate to Settings > Payments > Setup Payment Gateway.
  2. Click the Enable Gateway tab.
  3. On the Enable Gateway tab, click Edit and then select the payment gateway integrations that you want to enable for your tenant.
  4. Click Save

The gateway integrations that are enabled will be displayed in the Gateway Type drop-down list when creating a gateway instance.

On this page, you can also disable payment gateway integrations. Make sure you have read Disable payment gateway integrations before you disable a gateway integration.

Configure a payment gateway instance

Perform the following steps to configure a payment gateway instance in Zuora:

  1. Click your username in the upper right and navigate to Settings > Payments > Setup Payment Gateway
  2. On the Configure Gateway Instance tab, select the payment gateway from the Gateway Type drop-down.
  3. Click Create Gateway.
  4. Enter the required information for the selected gateway such as basic information, credentials, and rules.
  5. Click Save Gateway Information.

Common fields

The following fields are available for every payment gateway configuration in Zuora

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
  • Verify new payment method (optional)
  • Verify updated payment method (optional)
  • Payment gateway number


Choose a name that identifies this payment gateway profile. This name can be anything you want. We recommend using a name that helps your users identify what the payment gateway is used for. This is particularly important if you use our multiple payment gateways feature.

A best practice is to use only alphanumeric characters for payment gateway names. Avoid using special characters such as -, _, | because it might cause potential issues.

If you decide to change the payment gateway name, you must first deactivate the gateway prior to changing the name.

Use Gateway Test Environment

You can use your gateway’s test environment to ensure that your gateway integration with Zuora is working correctly. Select the Use Gateway Test Environment check box to direct your transactions in Zuora to your payment gateway's test environment or test simulator. Zuora will automatically mark all transactions as test and route the transactions to the correct test environment. If you are setting up a payment gateway profile that uses the test environment, be sure to name your gateway profile so that users are aware it is used for testing. For example, you can name your gateway "PayPal - US (Test)."

Gateway errors

Zuora passes all error codes directly from the gateway. If you receive an error while testing your payment gateway, see the payment gateway's documentation for more information about their error codes. 

Cards Accepted

Select the cards you want to accept when configuring your payment gateway. Make sure your gateway's merchant account is also configured to support the same cards you have configured in Zuora. If you submit a transaction for a card type that is not enabled in your merchant account, it will result in an error stating the CardType is not supported or that you are not signed up for that tender type. Additionally, if your company has never processed cards in Zuora, go to Settings > Payments  > Payment Methods and ensure the Credit Card payment method is selected. 

For more information about the card brands supported by gateways, see Supported payment methods.

Verifying payment methods

In gateway settings, the Verify new payment method and Verify updated payment method options are enabled by default to avoid storing invalid payment methods in Zuora, which will fail when your customers attempt to make payments. When either or both of these two options are enabled, Zuora Payments (within the Zuora UI and Zuora API) submits key information to the payment gateway to authorize all payment methods for authenticity and fraud prevention. The information passed to the payment gateway will include the Default Authorization Amount (which defaults to $1 in Zuora Payments, but can be customized as needed), as well as other payment method information. The authorization request also charges the payment method the default authorization amount, which is subsequently and automatically reversed by Zuora.

If these two settings are not enabled, the payments might fail because more and more gateways require that the payment method must be verified before making payments. Hence, it is strongly recommended to keep these two settings enabled to ensure the mandated information is returned and the payment is processed.

Payment gateway number

To identify a payment gateway, Zuora now supports an additional field named ‘Payment gateway number’ that allows you to input a number manually or system generate the number with the prefix PG- followed by an 8-digit number. For example, PG-00000001. This number that you enter is editable. Ensure to use a number that is unique and holds a maximum length of 40 characters. 

Note: The payment gateway number is not editable if it is in the active status. To edit the number, ensure to deactivate the gateway. 

Authorization timing

You can configure the gateway to authorize the payment method at either or both of the following times:

  • When a payment method is created, if Verify new payment method is enabled
  • When an existing payment method is updated, if Verify updated payment method is enabled

These are the only times that authorization for a payment method occurs.

The authorization is not performed when subsequent payment transactions are processed through Zuora Payments. One-cent authorizations verify the accuracy of the account and transit routing numbers for the payment method. It is standard practice for many businesses to authorize a payment method for one cent prior to charging it for payment.

Authorization amounts

Zuora payment gateway configuration allows you to set an authorization amount of your choice (it can be $0.00, $0.01, $1.00 or other amount). The authorization amount will be withheld from the end-user's account, but Zuora will automatically void the authorization within 24 hours of the original authorization.

Although many financial institutions accept one cent, or even $0.00, authorizations, many banks do not accept authorizations where the authorization amount is too small (for example, $0.01). These banks will reject payment methods that may or may not be valid simply due to the small authorization amount. This will affect payment methods set up through the Payments UI and the API. In these cases, change the default authorization amount.

When deciding to set the authorization amount, especially if the amount is to be $0.00, consider the following factors:

  • Make sure your payment gateway and processor both accept $0.00 authorizations. For example, the PayPal payment processor currently does not accept $0.00 authorizations and will recognize that as an invalid amount. If you are using Website Payments Pro (which uses the PayPal Processor), you will not be able to submit $0.00 authorizations.
  • Support of $0.00 authorization will also vary by credit card type. For example, Visa requires $0.00 authorizations, or else Visa will charge additional fees to the merchant unless the authorization amount is immediately reversed (which Zuora handles automatically).  For more information, see a PayPal article that discusses authorization amounts, Visa's requirements, and the Account Verification Program that require authorization amounts to be $0.00.

Configuration Fields Specific to Gateways

For more information about the configuration fields specific to the gateway, see the individual article for each gateway integration.

Specify a default payment gateway for your tenant

If you have multiple payment gateway instances set up in Zuora, specify a default gateway by completing the following steps:

  1. Click your username in the upper right and navigate to Settings > Payment Settings > Setup Payment Gateway.
  2. On the Configure Gateway Instance tab, find the gateway you want to use as the default, and then click Make Default under Action.

The default payment gateway you choose will be used to process payments for your customer accounts. If another payment gateway is selected in the Customer Account > Billing and Payment Info > Payment Gateway field, the payment gateway specified for the customer account takes precedence over the default payment gateway of the tenant.

Edit a payment gateway instance

To edit a payment gateway:

  1. Click your username in the upper right and navigate to Settings > Payment Settings > Setup Payment Gateway.
  2. On the Configure Gateway Instance tab, find the gateway you want to edit, and then click Edit under Action.
  3. Edit the information for the selected gateway.