Skip to main content

Setting Up Payment Gateways

Zuora

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

Name

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.

It is strongly recommended to keep these two options enabled. You can disable either or both of them by clear the options if needed.

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.

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

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.