Skip to main content Gateway

Zuora Gateway provides payment gateway services that provides online credit card and e-Check payment processing. This gateway is pre-integrated with Zuora and is both easy to configure and use.

Configure the Gateway

To set up as your gateway, enter your credentials in the Payments Settings > Setup Payment Gateway page. When selecting a Gateway Type, choose

Common Fields for Configuration

There are some common fields you must complete for every gateway configuration. We recommend reviewing our Setup Payment Gateway documentation for information on these common fields: 

  • Name
  • Use Gateway Test Environment

If you enable Use Gateway Test Environment, you must use developer account credentials, and not the merchant credentials. If you are using the production gateway (test or non-test environment), you must use the merchant credentials.

  • Cards Accepted
  • Default Authorization Amount
  • Verify new payment method (optional)
  • Verify updated payment method (optional)

In addition to the common fields, every gateway has unique requirements and information (such as credentials and certain rules) that you must provide to configure the gateway in Zuora. Credentials

Your credentials will be obtained from and configured in Zuora. 

To configure the payment gateway in Zuora, you must enter your API Login ID and Transaction Key in the Setup Payment Gateway page. See's Access Settings document for help determining your API Login ID and Transaction Key, or if you need to obtain a new Transaction Key.

Testing Your Configuration

We recommend that you test your payment gateway by using both your payment gateway's test and production (live) environments.  Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

Accessing Your Gateway's Test Environment

Some payment gateways provide separate credentials for merchants to access their testing (or certification) environment, some gateways use the same credentials for testing as for the production (live) environment but direct test transactions to a different URL, and other gateways do a little of both. provides you the ability to both test your transactions using a developer's test account as well as testing your transactions in your live account in test mode. Testing in both your developer's account and live account in test mode are recommended by We recommend reviewing this article before you begin testing.

How to Request an Developer Account for Testing

You can sign up for a test account on the Developer website. Once you have signed up, you will receive an email with your account information as well as a list of frequently asked questions and answers

Accessing the Test (Certification) or Production Environment from Zuora

When configuring the payment gateway in Zuora, you can indicate whether you would like to use the test environment or the production environment. 

  • If you select Use Gateway Test Environment, Zuora will direct payment transactions to the certification environment at
  • If you do not select Use Gateway Test Environment, Zuora will direct payment transactions to your production environment at

Test Credit Cards and Testing Scenarios

We recommend you to contact to request a set of test credit cards and testing scenarios. When you establish an Developer Test Account,  you will receive an email containing your test credentials and some test credit card numbers. has online documentation on testing, test credit cards, and testing scenarios. Here are some documents to review before you begin testing: 

If you receive an error message when adding credit cards, you may need to change or remove the encapsulation setting from your merchant account. Access your merchant account, click Settings, then click Direct Response > Transaction Response Settings. Remove the single quote setting in the Encapsulation Character field and click Save.

General Testing Information

Integration Testing

Zuora owns and manages the integration to on an ongoing basis, thoroughly testing the integration with every new release. The integration documentation is helpful if you are integrating directly with your website, however, you do not need to perform any integration or certification testing to submit transactions to via the Zuora application. The intended audience for the integration guides are technical integrators, however, these documents can be helpful to non-technical integrators who can refer to it for information on testing and troubleshooting gateway errors (as described below). 

Performance and Volume Testing

In general, gateway testing environments are intended to give merchants the opportunity to test their gateway and integrations to their gateway, in order to work out any bugs before going to the production environment. Some gateway test environments are shared amongst multiple merchants, and other gateways provide unique testing environments for each merchant. Additionally, gateway test environments (also referred to as certification or sandbox environments) do not have the same high availability or performance capability as production environments. As such, they are not intended for load testing. Merchants performing high volumes of load testing that puts a stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended.

Troubleshooting Gateway Errors

For failed payments processed using the payment gateway, Zuora Payments will provide the gateway Response Reason Code (for example, 44) and Response Reason Text (for example, This transaction has been declined).

To view the current status of the gateway, go to this location:

To find more information on payment gateway errors:

  1. Search the online documentation for information on response codes:
  2. Look up the transaction by the transaction ID number (in the Zuora payment detail page, this is the Reference ID and Secondary Reference ID numbers) in your merchant account to see if more information is provided; often you will see more than just the response (reasons) code and response message in Zuora.
  3. If you require additional information, you can contact Support directly at (801) 492-6450 and ask to be transferred to customer support. The Customer Support representative will ask you for:
    • Your Account’s Gateway ID number. This is required for them to support you and log a case.
    • The name of business (your company name).
    • The name, email address, and phone number of the person requesting support (that is, your name, email address, and phone).
    • The Transaction ID (in Z-Payments, this is the Reference ID) for the failed payment. 

Make Sure You Are Not Re-Trying an Invalid Card Too Many Times

We recommend that you check the payment in Zuora to see how many times the same payment method has been re-tried for payment and failed. If there have been several retries, check the error messages from the beginning with the first failure and the more recent failures to determine if the error message is the same. If a merchant tries to process a payment against the same credit card too many times despite receiving errors, this could trigger warnings to the card issuing bank. The card issuing bank may place an alert on the account and not allow any further transactions from the merchant using that payment method. When a merchant has been flagged, the error received on the payment may not state the reason why instead it might be a generic error such as 2 - Declined. In this case, the merchant (Zuora customer) should work with their merchant acquirer/processor to see if they can identify the problem with the payment method. If the processor does not know, then the merchant and/or the cardholder can try calling their card issuing bank to look into the issue

General Decline Errors (Including "2-This transaction has been declined")

General credit card decline errors from may have a Response Reason Code "2" and Response Reason Text "This transaction has been declined." General declines are fairly common, but a high rate of decline with this error is worth investigating further with your payment gateway and processor to rule out any issues with your merchant account. If you notice the declines happening with a specific card issuing bank, you may want to contact that bank to find out more information. 

Reasons for a general decline include: 

  • Insufficient funds in the card holder's account.
  • The card issuing bank does not allow internet transactions on the card.
  • The card is invalid (for example, it is canceled).
  • The card requires verbal authorization for transactions.
  • The merchant has been blocked from charging this card for payment. 

If you experience a very high number of transactions with this error, contact your merchant services provider to review your account configuration and status of the account. Since receives the decline from the processor who receives it from the card issuing bank, may refer you to your processor or merchant services provider for assistance.

Limited Free Trials and Credit Card Declines

If your company offers a limited free trial where you obtain and authorize credit cards in advance, but charge for payment on a future date (such as tomorrow, a week, or a month later) there's a risk that the credit card may no longer be valid when the future payment is collected (in gateway terminology, this is sometimes referred to as capturing a payment). The status/validity of a credit card can change easily and frequently. A customer's credit card can have sufficient funds today, but the customer makes a large purchase tomorrow that results in their account being low in funds. If you happen to charge their card when their account has insufficient funds, you will get a credit card decline. The same customer can pay off their credit card debt tomorrow, and their card will once again be valid with sufficient funds. For this reason, we recommend configuring your payment retry rules to retry credit cards (for example, you can retry a card once every 24 hours, up to a maximum of 3 attempts).There are many benefits to offering limited free trials, but its important to understand how a credit card can be valid one day and be declined the next. Again, if you feel these types of declines are occurring at a high rate, please contact your payment gateway and processor immediately to investigate the issue. 

Response codes for troubleshooting refunds

The following response codes can be returned by the gateway for refund problems.

Response Code Response Reason Code Response Reason Text Notes Next Steps
3 11 A duplicate transaction has been submitted. A transaction with identical amount and credit card information was submitted two minutes prior. Wait 2 minutes before creating another refund for the same account.
3 54 The referenced transaction does not meet the criteria for issuing a credit. None A refund can only be issued once a payment has settled. If the payment has not settled, you can void a payment instead of issuing a refund.

Additional Gateway Information 

Email Notification of Payment Receipt

Both and Zuora have email notifications that can be configured to send out payment receipts when a payment has been processed. See Email Receipt documentation for information on how to configure the email notification in your gateway. Zuora passes along the customer's email address to with the payment transaction so if you have this notification enabled, your customer will receive the below Customer Receipt/Purchase Confirmation.

The following is a sample of the email from

From: "JOHN DOE" <> 

To: "Jan Smith" <>

Sent: Thursday, January 12, 2012 at 11:02 AM
Subject: ABC Company Customer Receipt/Purchase ConfirmationThank you for your order!
Order Information
Merchant:   ABC Company
Description:        null
Invoice Number:     INV00000295
Customer ID:        ABC00000100

Billing Information
Jan Smith
United States

Shipping Information
Total:              US $99.00
American Express Date/Time:12-Jan-2012 11:02:22 AM PT
Transaction ID:     3084961236


John Doe
Billing Manager, ABC Company

Creating Non-Referenced Refund with

Zuora supports creating non-referenced refunds using credit cards via You must have Expanded Credit-Return Capabilities (ECC) enabled by to use this feature.

Using ACH with

Zuora supports ACH via's (electronic check payment method). Zuora supports eCheck payments that use the WEB or CCD transaction types. See Using ACH with for more information.