Skip to main content

Set up and configure a CardConnect gateway instance


Set up and configure a CardConnect gateway instance

Set up and configure a CardConnect 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.


  • Enable the CardConnect payment gateway integration for your tenant. See Enable payment gateway integrations for your tenant for instructions.
  • Before you configure CardConnect in Zuora, enable your CardConnect merchant account. Only the FTS version of the CardConnect gateway is supported. 
  • Enable refunds without reference in CardConnect at the Merchant Id level.


Take the following steps to set up and configure a CardConnect 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 CardConnect 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. Zuora recommends reviewing Setting Up Payment Gateways for information on these fields: 

  • Type
  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
    The default can be zero or higher.
  • Verify new payment method (required)
  • Verify updated payment method (optional)

CardConnect restricts one currency per Merchant ID.

Specific configuration fields

The following fields are specific to the CardConnect gateway integration:

CardConnect's support for multiple Merchant IDs is an Early Adopter feature. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

  • Merchant IdUsername, and Password: For the CardConnect gateway, these fields are API authentication credentials. The values for these fields must be obtained from CardConnect.
  • Enable Custom Merchant ID: Select this checkbox if you want to use the Merchant ID specified in the Merchant Id Custom Field setting.
  • Merchant Id Custom Field: Enter the API name (without __c) of the Merchant ID custom field that was set up on the Account object. The Merchant ID custom field type must be text. After you specify a value for this field, the Merchant ID custom field with the specified value will be used for all CardConnect API requests.
  • Enable Merchant-specific Endpoint: Select this checkbox only if CardConnect has provisioned an endpoint specifically for your merchant account. With this setting enabled, Zuora connects to the CardConnect endpoint defined in Merchant Endpoint Prefix Custom Field, and transactions are processed through this endpoint.
  • Merchant Endpoint Prefix Custom Field: Specify the prefix of the endpoint that CardConnect has provisioned specifically for your merchant account. For example, if you enter the prefix MerchantSpecificEndpoint in this field, the endpoint for the UAT environment will be and the endpoint for the production environment will be You can get the endpoint prefix information from CardConnect.

    This field takes effect only if the Enable Merchant-specific Endpoint field is selected.

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.

You can use the test card information and testing scenarios provided by the gateway vendor to test your integration. See Testing Your Integration in CardConnect Developer Center for details.

In CardConnect UAT environment, a payment amount in the $1000-$1999 range will trigger amount-driven response code testing to return a specific response code. If you do not intend to test specific response codes, to avoid failed payments, use a payment amount that is not in this range. See Testing with Amount-Driven Response Codes in CardConnect Developer Center for details.