> ## 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

> Connect a Stripe account to Payrails with one-click onboarding, then configure statement descriptors and embedded SEPA Direct Debit.

<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 payment orchestrator
> * Use **Stripe Payments** and want to onboard their **Stripe account** using a one-click flow that automatically imports their credentials.

## Create and configure a Stripe integration in Payrails

Following are the initial steps to setup stripe:

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.

![Payrails integrations page with Add instance flow for Stripe](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/paypal-image-01.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=d1d79723d4737a3342d8c86f8486777e)

## Step 1: Choose the integration type

Select **Payment** as integration type and continue to the next step.

![Payrails integration type selection with Payment selected](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-01.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=1abff5a34cd63736c653202ed3a9c619)

## Step 2: Choose the provider

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

![Payrails provider selection with Stripe selected](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-02.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=f336d7c7f02275b7e0c7d4734fad91ae)

***

## Step 3: Configure your Stripe integration

Payrails connects to your Stripe account through Stripe's OAuth flow, so you don't copy any API keys or webhook secrets.

### Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration.

### Select payment methods

Under **Payment methods**, select the payment methods you want to enable.

![A screenshot showing the Stripe payment methods selection in Payrails.](https://mintcdn.com/payrails-42074109/To59SEkYYPq19nmx/images/docs/orchestration/integrations/stripe-payment-methods.png?fit=max\&auto=format\&n=To59SEkYYPq19nmx\&q=85\&s=0901278c70225cf00946f94013947edc)

### Connect your Stripe account

Select **Save account**. A dialog will open explaining the next step.

![Payrails dialog prompting to continue Stripe connection](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-05.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=72033dcf4ff8b28896088b05d02c41fb)

Select **Go to Stripe** and a new window opens to Stripe's authorization page.

![Stripe authorization window for connecting account to Payrails](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-06.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=78d3963d3b6829c3e19a3d9af79a932d)

**In Stripe (popup window)**

* Sign in with the Stripe account you want to connect, if you're not already signed in.
* Review the permissions Payrails is requesting and authorize Payrails.
* The popup closes automatically and Payrails imports your Stripe credentials in the background.
* When saving completes, you land on the main window where you can see the success message and later on redirected to integration's details page with the **Enabled** status.

![Payrails success message after Stripe account connection](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-07.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=cab873e32afdb4df4b1e7580e167767c)

Your Stripe integration is now ready to process payments.

***

### Editing an existing Stripe integration

In edit mode, when you re-open a Stripe Connect integration, the configuration screen identifies the currently connected Stripe account ID and lets you choose between keeping the existing connection or connecting a different Stripe account.

When you select **Save account**, a dialog offers two options:

* **Keep existing** — preserve the current connection.
* **Connect new account** — start a fresh OAuth flow with a different Stripe account.

![Payrails Stripe edit dialog with keep existing or connect new account options](https://mintcdn.com/payrails-42074109/sujy1gNo9mr-Fy-6/images/docs/stripe-image-08.png?fit=max\&auto=format\&n=sujy1gNo9mr-Fy-6\&q=85\&s=f4ad88e71c0738edf538a94e39e7c1b0)

***

## Request fields for Stripe

Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Stripe when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Stripe as the PaymentIntent amount and currency. |
| `meta.customer.email` | Required | When you save the card for a new Stripe customer. Sent as the customer email. |
| `merchantReference`, `holderReference` | Optional | Sent as PaymentIntent metadata. Payrails uses `holderReference` to find or create the Stripe customer. |
| `meta.customer.name`, `lastName`, `phone`, `country.code` | Optional | When you save the card. Sent as the customer's name, phone and country. |
| `meta.order.billingAddress` | Optional | Sent as the card's billing details. |
| `meta.order.deliveryAddress` | Optional | Sent as the shipping address. |
| `meta.order.description` | Optional | Sent as the PaymentIntent description. |
| `meta.order.softDescriptor` | Optional | Sent as the statement descriptor or its suffix. Refer to [Statement descriptor suffix](#statement-descriptor-suffix). |
| `meta.risk.sessionId` | Optional | Sent as the Radar session. |
| `meta.risk.skipPaymentProviderRules` | Optional | `true` skips your Radar rules for this payment. |
| `meta.risk.threeDSMode` | Optional | `Force` requests 3D Secure. |
| `meta.tags` | Optional | Sent as metadata on the PaymentIntent, payment method and customer. |

***

## Configure Stripe settings

Some Stripe integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

### Statement descriptor suffix

**Statement Descriptor (Suffix)** controls how Payrails sends the soft descriptor from `meta.order.softDescriptor` in your payment request. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Setting | What your customer's statement shows |
| :- | :- |
| On | The shortened descriptor (prefix) set in your Stripe account, followed by the soft descriptor |
| Off | The soft descriptor, in place of your full statement descriptor |

Turn this on if your Stripe account has a shortened descriptor set. The setting has no effect on payments without a soft descriptor.

### Embedded SEPA Direct Debit

By default, customers paying with SEPA Direct Debit go to a page hosted by Stripe to confirm the mandate. Turn on **Embedded** under **SEPA Direct Debit** in **Payment methods** to complete the payment on your own checkout page instead. Payrails saves the mandate for future debits.

> [!WARNING]
>
> Embedded SEPA Direct Debit only works if your checkout collects everything Stripe needs. Payrails rejects the payment when any of these is missing:
>
> * The customer's IBAN, collected in your checkout
> * An email address in `meta.order.billingAddress.email` or `meta.customer.email`
> * The customer's IP address and user agent in `meta.clientContext.ipAddress` and `meta.clientContext.userAgent`
> * An amount in EUR greater than zero

### Stripe Connect

When you connect through Stripe's OAuth flow, Payrails turns on Stripe Connect for the integration and processes payments on your connected Stripe account. You don't need an API key, and the setting doesn't appear in the form.

***

## Next steps

1. Run a test payment using a Stripe [test card](https://docs.stripe.com/testing).
2. Verify that:
   * The payment appears in Stripe.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md)


## Related topics

- [Stripe](https://docs.payrails.com/docs/integrations/dispute-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.