> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Stripe

> Configure a Stripe Disputes integration, with or without Stripe Connect, so Payrails processes your chargebacks.

<picture noZoom>
  ![Stripe logo](https://assets.payrails.io/img/logos/stripe/logo-full-bleed.svg)
</picture>

> [!NOTE]
>
> **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

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.

> [!NOTE]
>
> **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.

![Payrails Portal New instance step 1 of 3, Select integration type, with Dispute selected](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-1.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=8f278327019694b7716fc9a277f6e26e)

## Step 2: Choose the provider

* Select **Stripe** and continue to the next step.

![Payrails Portal provider selection with Stripe selected and the Continue button](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-2.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=16f767e09c990f22a9c6701a79dbb205)

***

## Step 3: Configure your Stripe integration

> [!TIP]
>
> **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](https://dashboard.stripe.com/login) 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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-3.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=a23d4b8ba1cfef9b89251968ffab0cf2)

***

### Service account (Stripe Connect only)

> [!TIP]
>
> 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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-4.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=a8d9cf67ee2ea03f5a8cd6cf96e6912f)

***

### 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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-5.jpg?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=90421b821ec5be2ba3b991410cf411f2)

**In Payrails**

* Paste the value into the **Merchant Stripe account ID** field.

***

### Secret API key

> [!TIP]
>
> 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)

> [!TIP]
>
> Payrails uses Stripe webhooks to receive asynchronous chargeback status
> updates.

> [!WARNING]
>
> If you are using Stripe Connect, skip this part.

> [!WARNING]
>
> 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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-6.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=98ab99a82f2960272bb8f89a6288e1b4)

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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-7.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=42bb7135aee640e02f1049f7f3978c66)

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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-8.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=4ff9d57cee6eeec2059e6c963ebe294c)

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](https://mintcdn.com/payrails-42074109/qmI75fSRDVw58Kgk/images/docs/chargebacks/integrations/stripe-chargeback-integration-9.png?fit=max\&auto=format\&n=qmI75fSRDVw58Kgk\&q=85\&s=3d07b9b22afa46276853a2cade55bf30)

Your Stripe integration is now ready to process chargebacks.

***

## Next steps

1. Run a test payment triggering a chargeback using a Stripe [test card](https://docs.stripe.com/testing#disputes).
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.


## Related topics

- [Stripe](https://docs.payrails.com/docs/integrations/payment-providers/stripe.md)
- [BLIK via Stripe](https://docs.payrails.com/docs/integrations/payment-methods/blik/stripe.md)
- [PAYCO via Stripe](https://docs.payrails.com/docs/integrations/payment-methods/payco/stripe.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.