Skip to main content

Checkout.com payment gateway integration

Zuora

Checkout.com payment gateway integration

Checkout.com allows you to build flexible payment flows, collect payments quickly and securely, and accept payments from various payment methods. Zuora’s integration with Checkout.com makes it simple to accept recurring and one-off payments via credit cards, bank transfer, or ACH.

In addition, Zuora provides a Payment Method Updater to work with the Account Updater of Checkout.com. This feature helps keep Zuora and you informed when card members change, replace, or upgrade their card information. For more information, see Configure Checkout.com Payment Method Updater.

Supported payment methods

The Checkout.com gateway integration supports the following payment methods:

  • Credit Cards, including:
    • Visa
    • Mastercard
    • American Express
    • Discover
    • Diners Club
    • JCB
    • China Union Pay 
  • SEPA
  • ACH
  • Apple Pay

    Support for the Apple Pay payment method on Checkout.com is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.

Support for mandate creation

Among the supported payment methods, Zuora supports mandate creation for SEPA payment methods. Zuora will generate and pass the mandate to the gateway.

Stored credential transactions

The Checkout.com gateway integration includes support for the Stored Credential Transactions framework. For details about the supported payment methods, see Support for stored credential transactions overview.

Supported payment operations

The Checkout.com integration supports the following payment operations:

  • Validate
  • Payment
  • Refund

Support for 3D Secure 2.0 

Zuora's Checkout.com gateway integration provides support for 3DS2 through the embedded iFrame of Payment Pages 2.0. To enable 3DS2, see Enable 3DS2 for Checkout.com gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information.

After 3DS2 is enabled in the Payment Pages settings, you can use the 3DS Challenge Indicator configuration field to indicate your preference for whether or not a 3DS challenge should be performed. See Additional configuration fields for more information.

The "Best practices" section in Zuora’s implementation of 3D Secure 2.0 also provides best practices for reducing the possibility of failed transactions due to 3DS2 authentication errors.

Supported Gateway Reconciliation event types

The Checkout.com integration supports the following Gateway Reconciliation event types for all supported payment methods:

  • Settlement
  • Rejection
  • Chargeback

Set up Checkout.com integration

After the Checkout.com gateway integration is enabled in your tenant, set up the payment gateway.

  1. Click your username at the top right, and navigate to Settings > Payments > Set Up Payment Gateway.
  2. From the Gateway Type dropdown list, select checkout.com.
  3. Click create gateway.
  4. Complete the information for the gateway instance. See below for more information about the fields.
  5. 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: 

  • Type
  • Name
  • 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 section below 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 allowed for this field was updated in the 2022.10.R1 release. If you have not provided a new bearer API key for ACH transactions 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. No action is required for Credit Card transactions.

  • 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 section below 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 iscorporate; 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 "3ds.challenge_indicator": "challenge_requested" You want a challenge to be performed.
    Challenge Requested Mandate "3ds.challenge_indicator": "challenge_requested_mandate" Local requirements demand a challenge be performed.
    No Challenge Requested "3ds.challenge_indicator": "no_challenge_requeste" You do not want a challenge to be performed.
    No Preference "3ds.challenge_indicator": "no_preference" You have no preference whether or not a challenge should be performed.

Gateway Reconciliation for Checkout.com

Gateway Reconciliation for Checkout.com is supported for Credit Card and SEPA payment methods. It is not available for ACH or Apple Pay for now.

Before configuring and using Gateway Reconciliation for Checkout.com, complete the following tasks:

  • Send an email to support@checkout.com to add your merchant account's Daily-Full-Edition and Disputes Hub reports to Zuora's checkout.com gateway integration.
  • Get your API key from Checkout.com dashboard. This API key is required for configuring Gateway Reconciliation for Checkout.com gateway integration when setting up the gateway integration.
  • Contact Checkout.com to get your SFTP username. This SFTP username is required for configuring Gateway Reconciliation for Checkout.com gateway integration when setting up the gateway integration.

Checkout.com hosts an SFTP server for Zuora, where Checkout.com uploads transaction reports for merchants. These reports are aggregated in a single folder for each merchant. Each merchant folder contains its day-to-day reports. Two reports are generated on a daily basis, including a Full edition report and a Disputes report. 

  • The Full edition report contains settlements and rejections for credit cards and SEPA.
  • The Disputes report contains chargeback data for credit cards and SEPA.

For the detailed columns in the two reports, see Checkout.com's documentation for more information.

Support for Apple Pay

Support for the Apple Pay payment method on Checkout.com is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.

Follow the instructions in Apple Pay on Web to learn how to configure Apple Pay in Zuora.

You can also refer to Checkout.com's Set up Apple Pay guide to get a better understanding of the Apple Pay setup. Note that you should skip Step 2: Add Checkout.com as a payment processor of this guide because Zuora's payment processing certificates will be used here.

Testing Your 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:

Limitations

  • Since Checkout.com uses auto-capture by default, payment requests are captured very quickly. Therefore, payments cannot be cancelled or voided using the Checkout.com gateway. Once made, payments can only be refunded later.
  • Non-referenced refunds (credits) are not supported by the Checkout.com gateway integration.
  • Gateway Reconciliation for Checkout.com is not supported for ACH or Apple Pay for now.
  • Limitations specific to Apple Pay:
    • Apple Pay is enabled by default on Checkout.com unless payments are to be processed in the United Arab Emirates or Saudi Arabia. If you operate in these regions, contact your Customer Success Manager at Checkout.com to have Apple Pay enabled.
    • If you plan to process any Apple Pay payments through an entity outside of the European Economic Area (EEA), contact your Customer Success Manager or integration engineer at Checkout.com to have Apple Pay enabled.