Skip to main content

Setting Up Payment Gateways


Setting 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.

Enabling a Payment Gateway for Your Tenant

The payment gateways must be enabled in your tenant before you can start the configuration.

Submit a request at Zuora Global Support to enable this feature or service.

Configuring a Payment Gateway

Perform the following steps to configure your payment gateway:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway.
  2. Select the payment gateway from the Gateway Type drop-down.
  3. Click create gateway. In the New Gateway page appears. 
  4. Enter the required information for the selected gateway such as basic information, credentials, and rules.
  5. Click save gateway information.

See Common fields and Supported Configuration Fields By Gateway for more information about the required fields.

Specifying a Default Payment Gateway

If you have multiple payment gateways set up in Z-Payments, you must specify a default gateway by doing the following:

  1. Navigate to Settings > Payment Settings > Setup Payment Gateway.
  2. Go to the gateway you want to use as the default, under Action (on the right) click Make Default.

The default payment gateway you choose will be used to process payments for your customer accounts unless the customer account is set up to use a specific payment gateway (under the customer account > billing and payment Info > payment gateway field).

Payment Gateway Information - Common Fields

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

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

See Supported Configuration Fields By Gateway for more information about additional required fields. 


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. 

Credit Cards Accepted

Select the credit cards you want to accept when configuring your payment gateway. You can choose from Visa, MasterCard, American Express, or Discover. Make sure your gateway's merchant account is also configured to support the same credit cards you have configured in Zuora. If you submit a transaction for a credit 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 credit cards in Zuora, go to Settings > Payments  > Payment Methods and ensure the Credit Card payment method is selected. 

Verifying Credit Cards

In gateway settings, when you enable either or both of the Verify new credit card and Verify updated credit card options, Zuora Payments (within the Zuora UI and Zuora API) submits key information to the payment gateway to authorize all credit cards 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 the credit card holder's billing address, and the credit card security code (the latter two are passed to the gateway only if it is submitted to Zuora). Billing address verification is based on the AVS settings established by the merchant account settings in the payment gateway. The authorization request also charges the Credit Card payment method the default authorization amount, which is subsequently and automatically reversed by Zuora.

Zuora recommends that you enable the verify options to avoid storing invalid payment methods in Zuora, which will fail when your customers attempt to make payments.

Card Authorization Timing

You can configure the gateway to authorize a credit card when a payment method is created (if you enable Verify new credit card) and when an existing payment method is updated (if you enable Verify updated credit card). These are the only times that an authorization for a payment method (card) occurs.

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

Card Authorization Amounts

For Credit Cards, 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 cardholder's account, but Zuora will automatically void the authorization for you within 24 hours of the original authorization, ultimately not impacting the credit limit on the cardholder's account.

Although many financial institutions accept one cent, or even $0.00, authorizations, there many banks that do not accept authorizations where the authorization amount is too small (for example, $0.01). These banks will reject cards that may or may not be valid simply due to the small authorization amount. This will affect cards entered in the Payments UI as well as the API. In these cases, you can 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.

Editing a Payment Gateway

To edit a payment gateway:

  1. Click your username at the top right and navigate to the Setup Payment Gateway page.
  2. Go to the gateway you want to use as the default, under Action (on the right), and click Edit.
  3. In the page that appears, edit the information for the selected gateway.