Skip to main content

Set up and configure a GoCardless gateway instance


Set up and configure a GoCardless gateway instance

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


Create an OAuth 2.0 token in the Gateway Authentication payments setting. You will need to provide the OAuth token in the OAuth Token field when configuring the gateway instance. For more information, see the Configuration fields in a later section and the Payment Gateway Authentication article.


Take the following steps to set up and configure a GoCardless gateway instance:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway
  2. On the Configure Gateway Instance tab, select GoCardless from the Gateway Type drop-down list.
  3. Click Create Gateway.
  4. Complete the information for the gateway instance. See below for more information on the fields.
  5. Click save gateway information after entering the necessary information.

Configuration fields

Common configuration fields

There are some common fields you must complete for every gateway configuration. We recommend reviewing Setting Up Payment Gateways for information on these fields: 

  • Type
  • Name
  • Use Gateway Test Environment
  • Default Authorization Amount
  • Verify new payment method (required)
  • Verify updated payment method (optional)

Specific configuration fields

In addition to the common fields, complete the following settings:

  • OAuth Token: Select the created OAuth 2.0 token from the OAuth Token dropdown list. You can navigate to Payments Settings > Gateway Authentication to create a new token or view all available tokens. For more information about how to create OAuth tokens in Zuora, see Payment Gateway Authentication.

    One merchant account can have only one active OAuth token. The previous token is automatically expired on the GoCardless end when the new token is created. If a separate token is required because multiple environments are used, please contact GoCardless for a separate testing MID.

  • Access Token (read-only): Only available for the gateway instances created before Zuora Billing Release 289. 
  • Creditor ID (read-only): Only available for the gateway instances created before Zuora Billing Release 289. 
  • (Optional) Enable Batch Gateway Reconciliation (Legacy): Select this check box if you want to enable Gateway Reconciliation batch jobs for GoCardless. See Gateway Reconciliation for more information.

Note that for the GoCardless gateway instances created before Zuora Billing Release 289, the previously stored Access Token and Creditor ID credentials can continue to work, but you cannot update them anymore. If you want to switch to the OAuth authentication mode, you can create an OAuth token and select it from the OAuth Token dropdown list. The OAuth 2.0 authentication is then enabled for all subsequent requests.

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 real information. 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.

You can use the testing scenarios provided by the gateway vendor to test your integration. See Test bank details in GoCardless guides for details.