Skip to main content
Who should use this guideThis guide is intended for merchants who:
  • Use Payrails as a chargeback
  • Use Stripe Disputes (with or without Stripe Connect)

​
Create and configure a Stripe integration in Payrails

  1. Log in to the Payrails portal.
  2. Go to Settings → Integrations.
  3. Select Add instance to create a new Stripe 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 Dispute and continue to the next step.
Stripe chargeback integration 1

​
Step 2: Choose the provider

  • Select Stripe and continue to the next step.
Stripe chargeback integration 2

​
Step 3: Configure your Stripe integration

What you’ll need from StripeBefore you begin, make sure you have access to:
  • (Optional) Service / platform account ID (Stripe Connect only)
  • Stripe account ID
  • Publishable API key
  • Restricted secret API key
  • Webhook signing secret
Log in to your Stripe dashboard to complete this step.

​
Integration instance name

In Payrails
  • Enter an Instance name for your integration.
Stripe chargeback integration 3

​
Service account (Stripe Connect only)

Skip this section if you process disputes directly on your own Stripe account.
In Stripe
  • Go to Settings → Account details.
  • Copy the Service account ID (also called the platform account ID).
In Payrails
  • Paste the value into the Service account field.
Stripe chargeback integration 4

​
Merchant Stripe account ID

In Stripe
  • Go to Settings → Business.
  • On the Account details tab, copy the account ID (acct_ followed by a 16-character alphanumeric string).
Stripe chargeback integration 5 In Payrails
  • Paste the value into the Merchant Stripe account ID field.

​
Secret API key

Use a restricted API key to limit access scope and reduce blast radius if the key is compromised.
In Stripe
  1. In Developers, locate Restricted keys and select Create restricted key.
  2. Choose Providing this key to another website.
  3. Grant the minimum required permissions:
    • Charges (read/write)
    • Disputes (read/write)
    • Files (read/write)
    • Payment Intents (read/write)
    • Refunds (read/write)
    • Webhooks (read)
  4. Name the key and add https://www.payrails.com as the destination URL.
  5. Copy the generated API key.
In Payrails
  • Paste the value into the Secret API key field.

​
HMAC key (webhook signing secret)

Payrails uses Stripe webhooks to receive asynchronous chargeback status updates.
If you are using Stripe Connect, skip this part.
Create the webhook in the same mode (test or live) as your Payrails integration.
In Stripe
  1. Go to Developers → Webhooks.
  2. Select Add destination.
  3. Choose Your account, then Selected events, and enable only the following events: Stripe chargeback integration 6
  4. Select Webhook endpoint and continue.
In Payrails
  • Copy the Notification URL from the Account configuration section.
Stripe chargeback integration 7 In Stripe
  1. Configure the destination:
    1. Give the destination a descriptive name.
    2. Paste the Payrails Notification URL and
    3. Select Create destination.
  2. Copy the Signing secret.
Stripe chargeback integration 8 In Payrails
  • Paste the Signing secret into the HMAC key field.

​
Enable the integration

In Payrails
  • Select Save account to enable the integration.
The Enabled status indicates that the Stripe integration is active. Stripe chargeback integration 9 Your Stripe integration is now ready to process chargebacks.

​
Next steps

  1. Run a test payment triggering a chargeback using a Stripe test card.
  2. Verify that:
    • The dispute appears in Stripe.
    • The chargeback status updates correctly in Payrails.
  3. Once verified in test mode, repeat the setup in live mode.
Last modified on September 29, 2026