Guides
Go to payrails.com

Checkout.com

📘

Who should use this guide

This guide is intended for merchants who:

  • Use Payrails as a chargeback
  • Use Checkout.com Disputes

We use a server-to-server integration with Checkout.com, so your account must be enabled to process dispute. If this isn’t enabled, chargebacks 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 Workspaces
Workspaces 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 Dispute.
  • Continue to the next step.

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.com

Before 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

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

In Checkout.com

  1. Go to Developers.
  2. Select Create new 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

    • issuing:disputes-read

    • issuing:disputes-write

    • issuing:transactions-read

    • issuing:transactions-write


  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.

  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 chargeback 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:


  7. Save the webhook.

In Payrails

  • Paste the Signature key into the HMAC key field.

Enable the integration

In Payrails

  • Select Save account to enable the integration.

The Enabled status indicates that the Checkout.com integration is active.

Your Checkout.com integration is now ready to process chargebacks.

Next steps

  1. Run a test payment triggering a chargeback using a supported Checkout.com test card.
  2. Verify that:
    • The dispute appears in Checkout.com.
    • The chargeback status updates correctly in Payrails.
  3. Once verified in test mode, repeat the setup in live mode.

Updated 13 days ago