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.
Payrails Portal New instance step 1 of 3, Select integration type, with Dispute selected

​
Step 2: Choose the provider

  • Select Stripe and continue to the next step.
Payrails Portal provider selection with Stripe selected and the Continue button

​
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.
Account configuration section with the Integration instance name field, instance ID and notification URL

​
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 account form with the Service account, Publishable API key, account ID, API key and HMAC keys fields

​
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 Dashboard Business settings, Account details tab, showing the Account ID 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 event selection with the five charge.dispute events checked
  4. Select Webhook endpoint and continue.
In Payrails
  • Copy the Notification URL from the Account configuration section.
Account configuration section showing the Notification URL to copy into Stripe 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 Workbench webhook destination for Payrails, showing its endpoint URL and signing secret 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. Payrails Portal Integration instance details for the Stripe dispute integration, with status Enabled 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 October 19, 2026