Set up and configure a Checkout.com gateway instance
Set up and configure a Checkout.com gateway instance by using the information in this article, including the configuration procedure, descriptions of the configuration fields and references for testing the payment gateway.
After the Checkout.com gateway integration is enabled in your tenant, take the following steps to set up and configure a Checkout.com gateway instance:
- Click your username at the top right, and navigate to Settings > Payments > Set Up Payment Gateway.
- On the Configure Gateway Instance tab, select checkout.com from the Gateway Type dropdown list.
- Click Create Gateway.
- Complete the information for the gateway instance. See below for more information about the fields.
- Click Save Gateway Information.
Common configuration fields
There are some common fields you must complete for every gateway configuration. Zuora recommends that you review Setting Up Payment Gateways for information about these fields:
- Use Gateway Test Environment
- Cards Accepted
- Default Authorization Amount: This field is used only for credit card validation. You can validate the credit card payment method using 0 or non-zero authorization amount. Defaults to 1 in Zuora.
- Verify new payment method (optional):
With this checkbox selected, the validate call is triggered for any supported payment method when a new payment method is created.
For ACH, payment method verification is supported through the ValidiFi account validation service. To verify new ACH payment methods, you must enable the support for ValidiFi service and select this setting. For more information, see Enable the support for ValidiFi account validation for ACH on Checkout.com.
For SEPA, if this setting is selected, Source ID from Checkout.com must be entered in the MandateID field during the payment method creation.
- Verify updated payment method (optional):
With this checkbox selected, the validate call is triggered for any supported payment method when an existing payment method is updated.
For ACH, payment method verification is supported through the ValidiFi account validation service. To verify updated ACH payment methods, you must enable the support for ValidiFi service and select this setting. For more information, see Enable the support for ValidiFi account validation for ACH on Checkout.com.
For SEPA, this setting must be selected to have updated payment information reflected in Checkout.com.
- Enable gateway reconciliation: If you select this checkbox, it will trigger a daily job to reconcile all payment events processed through the gateway. See the Gateway Reconciliation for Checkout.com for details.
Additional configuration fields
The following fields are specific to this gateway integration:
- API Key: The bearer API key used for Credit Card and ACH transactions. You can obtain this API key by navigating to Developers > Keys in the Checkout.com dashboard.
The API key required in this field was updated in the 2022.10.R1 release.
- The creation of a new Checkout.com gateway instance with the old deprecated API key is not allowed.
- For ACH transactions, if you have not provided a new bearer API key since the 2022.10.R1 release, your ACH transactions cannot be processed because the existing API key has been deprecated as requested by the Checkout.com gateway. Please obtain a new bearer API key from the Checkout.com dashboard and enter it in this field.
- For existing gateway instances using the old deprecated API key, only credit card transactions are supported.
- API Key (SEPA): The API key used for SEPA transactions. You can obtain this API key by contacting Checkout.com support.
- SFTP Username (optional): This field is required for Gateway Reconciliation. Contact Checkout.com to get your username and enter it in this field. Your Zuora username and public key will be used to access the SFTP server. See the Gateway Reconciliation for Checkout.com for more information about Gateway Reconciliation.
- Default Soft Descriptor (optional): The default soft descriptor for payments. It is required for all Direct Debit payment methods.
- Merchant's Company Name (optional): This field is required if your customers try to add an ACH payment method and select Business Checking as the account type. The Checkout.com payment gateway requires that the Company Name is included in the request if the account type is
corporate; otherwise, the gateway will mark the transaction as
failed. The value is a maximum of 50 characters. Zuora recommends that you always specify this field for both existing and new gateway instances.
- 3DS Challenge Indicator: If 3DS2 is enabled in the Payment Pages settings, the selected indicator in this field will be passed to the gateway. For more information about this indicator, see the Checkout.com documentation. Ultimately, it is the issuing bank that determines whether a card needs to be authenticated through a challenge.
Option in the dropdown list Indicator to be passed Description Challenge Requested
You want a challenge to be performed. Challenge Requested Mandate
Local requirements demand a challenge be performed. No Challenge Requested
You do not want a challenge to be performed. No Preference
You have no preference whether or not a challenge should be performed.
Test the configuration
We recommend that you test your payment gateway 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 the following Checkout.com documentation for details: