Set Up Payment Gateways

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.