Skip to main content

Set up and configure an gateway instance


Set up and configure an gateway instance

Set up and configure an gateway instance by using the information in this article, including configuration procedure, descriptions of the configuration fields and reference for testing the payment gateway.


Before you set up and configure an payment gateway instance on your tenant, enable the payment gateway integration for your tenant. See Enable payment gateway integrations for your tenant for instructions.


Perform the following steps to set up and configure an 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 from the Gateway Type drop-down list.
  3. Click Create Gateway.
  4. On the gateway settings page, specify values for the configuration fields. See below for more information on the fields.
  5. Click Save Gateway Information.

Configuration fields 

Common configuration fields

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)

Specific configuration fields

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.

Test the 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.

Related information