Stripe

📘
Who should use this guide
This 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

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

Step 2: Choose the provider

Select Stripe and continue to the next step.

Step 3: Configure your Stripe integration

📋
What you’ll need from Stripe
Before 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.

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.

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

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

In Developers, locate Restricted keys and select Create restricted key.
Choose Providing this key to another website.
Grant the minimum required permissions:
- Payment Intents (read/write)
- Charges (read/write)
- Refunds (read/write)
- Webhooks (read)
Name the key and add https://www.payrails.com as the destination URL.
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

Go to Developers → Webhooks.
Select Add destination.
Choose Your account, then Selected events, and enable only the following events:
Select Webhook endpoint and continue.

In Payrails

Copy the Notification URL from the Account configuration section.

In Stripe

Configure the destination:
1. Give the destination a descriptive name.
2. Paste the Payrails Notification URL and
3. Select Create destination.
Copy the 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.

Your Stripe integration is now ready to process chargebacks.

Next steps

Run a test payment triggering a chargeback using a Stripe test card.
Verify that:
- The dispute appears in Stripe.
- The chargeback status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.