Skip to main content
Who should use this guideThis guide is intended for merchants who:
  • Use Payrails as a payment orchestrator
  • Use Checkout.com Payments
  • Are approved to process raw card data
We use a server-to-server integration with Checkout.com, so your account must be enabled to process raw card data. If this isn’t enabled, payments won’t work in production. Please contact your Checkout.com account manager or support team to activate it.

​
Create and configure a Checkout.com integration in Payrails

  1. Log in to the Payrails portal.
  2. Go to Settings → Integrations.
  3. Select Add instance to create a new Checkout.com integration configuration.
  4. Select the Workspaces where this integration should be available.
About WorkspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple Workspaces.

​
Step 1: Choose the integration type

  • Select Payment.
  • Continue to the next step.
A screenshot showing the integration type selection form.

​
Step 2: Choose the provider

  • Select Checkout.com.
  • Continue to the next step.
A screenshot showing the Checkout.com integration selected.

​
Step 3: Configure your Checkout.com integration

What you’ll need from Checkout.comBefore you begin, make sure you have access to:
  • Processing Channel ID (pc_XXX)
  • Checkout.com Access Key ID
  • Checkout.com Access Key Secret
  • Webhook signature key
Sign in to your Checkout.com dashboard to complete this step.

​
Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, as it is used in routing.
In Payrails
  • Enter an Instance name for your integration.
A screenshot showing the Payrails integration instance name field.

​
Account details

In Checkout.com
  1. Sign in to the Checkout.com Dashboard.
  2. Locate your Processing Channel ID in the account or processing channel settings.
  3. Copy the Processing Channel ID (pc_XXXX).
In Payrails
  • Paste the value into the Processing Channel ID field.
A screenshot showing the Checkout.com account fields.

​
API credentials

Payrails Checkout.com API credentials section In Checkout.com
  1. Go to Developers.
  2. Select Create new key.
Checkout.com dashboard page for creating a new API key
  1. In Key details, select Access key pair.
  2. Add a Description to help identify the key.
  3. Under Scopes → Customise → Custom scopes, enable:
    • disputes:accept
    • disputes:provide-evidence
    • disputes:view
    • files
    • gateway
    • sessions:app
    • sessions:browser
    • vault:instrument Checkout.com custom scopes selection for API key permissions Checkout.com key configuration options during API key setup
    Checkout.com API key setup showing processing channel options
  4. Select Allow any processing channel (or restrict if required).
  5. If needed, locate your Processing Channel ID here (pc_XXX).
  6. Select Create new key.
Checkout.com newly created access key pair details
  1. Copy the Access Key ID and Access Key Secret.
In Payrails
  • Paste the credentials into the corresponding fields.
A screenshot showing the Checkout.com API credential fields.

​
Webhooks (notifications)

Payrails uses Checkout.com webhooks to receive asynchronous payment status updates.
Create the webhook in the same mode (test or live) as your Payrails integration.
In Checkout.com
  1. Go to Developers → Webhooks.
  2. Select New webhook.
  3. Enter a name for the webhook.
  4. Paste the Notification URL from Payrails. A screenshot showing the Payrails integration instance name field.
  5. Generate a Signature key.
  6. Select:
    • All events
    • All entities
    • All processing channels
  7. Save the webhook.
In Payrails
  • Paste the Signature key into the HMAC key field.

​
Payment methods

In Payrails
  • Select the payment methods that should be enabled for this integration.
A screenshot showing the Checkout.com payment methods.

​
Request fields for Checkout.com

Send these fields in the authorize request for card payments, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to Checkout.com when you include them. For more about meta fields, refer to Meta fields.

​
Configure Checkout.com settings

Some Checkout.com integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting. You find them under Account details.

​
User-defined fields

UDF1 to UDF4 choose what Payrails sends in each of the four Checkout.com user-defined fields. Payrails sends them in the payment metadata on authorize, capture, refund and void, so you can search and report on them in Checkout.com. For more about meta fields, refer to Meta fields.

​
Mada CVV Patching

Turn on Mada CVV Patching if you process local mada cards and collect the CVV again when a customer pays with a saved card. Payrails then adds that CVV to the customer-initiated payment it sends with the stored Checkout.com card. Without a newly collected CVV, the setting has no effect.

​
Enable Mada Previous Payment ID

On merchant-initiated payments, Payrails sends a previous payment ID that links the payment to the customer’s earlier payment. By default it’s the card’s network transaction reference. Turn on Enable Mada Previous Payment ID to send the ID of the last successful Checkout.com payment on the card instead, for mada cards.

​
Enable non-SCA compliant behavior

Enable non-SCA compliant behavior changes two things on card and Google Pay payments:
  • When your request forces 3D Secure, Payrails asks Checkout.com for no challenge instead of a mandated challenge.
  • On a first payment that saves the card for subscription or unscheduled payments, Payrails sends the payment type as regular.
This behaviour doesn’t meet strong customer authentication (SCA) rules for payments in Europe. Turn it on only after your compliance team confirms it for your processing.

​
Enable the integration

In Payrails
  • Select Save account to enable the integration.
The Enabled status indicates that the Checkout.com integration is active. A screenshot showing the enabled Checkout.com integration. Your Checkout.com integration is now ready to process payments.

​
Next steps

  1. Run a test payment using a supported Checkout.com test card.
  2. Verify that:
    • The payment appears in Checkout.com.
    • The payment status updates correctly in Payrails.
  3. Once verified in test mode, repeat the setup in live mode.
→ Continue to: Test a payment
Last modified on October 12, 2026