> ## 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
> Generate Stripe live and sandbox keys, then connect Stripe as a data source for financial reports and transaction data.
This guide will help you generate the necessary API credentials and connect Stripe as a data source in Payrails to ingest financial reports and transaction data. With the self-serve flow you configure the integration yourself in the Payrails portal.
## Prerequisites
* A Stripe account with Administrator or Developer permissions
* Access to the [Stripe Dashboard](https://dashboard.stripe.com/)
## Overview
To ensure we can ingest data for both your production and testing environments, you will need to generate two separate API keys:
* One for **Live Mode** (production)
* One for **Test Mode** (sandbox)
We recommend using **Restricted API Keys** for both. This follows security best practices by limiting our access strictly to the reporting data we need.
***
## Step-by-step instructions
### Step 1: Generate your Live Mode Key
1. Log into your **Stripe Dashboard**
2. Ensure the **Test mode** toggle (usually in the top-right or top-left corner) is **OFF**
3. Navigate to **Developers** > **API keys**
4. Under the "Restricted keys" section, click **Create restricted key**
* *Note: Do not use the "Secret key" unless specifically required*
5. Name the key: `Payrails Live Reporting`
6. Under the **Permissions** section, configure the following access:
* **Core - Read:**
* **Balance** (balance\_read) — Required to retrieve the account balance snapshot
* **Balance Transaction Sources** (balance\_transaction\_source\_read) — Required to retrieve the balance transaction ledger that drives settlement and fee reporting
* **Charges and Refunds** (charge\_read) — Required to retrieve charge and refund objects so transaction-level fees resolve back to their originating payment
* **Customers** (customer\_read) — Required to retrieve Customer objects referenced by payments
* **Events** (event\_read) — Required for freshness and drift detection across Stripe state changes
* **Files** (file\_read) — Required to download the generated report files
* **Payment Disputes** (dispute\_read) — Required to enrich chargeback reporting with dispute reasons, evidence due dates, and timeline
* **Payment Intents** (payment\_intent\_read) — Required to retrieve PaymentIntent objects and link payments to Payrails metadata
* **Payouts** (payout\_read) — Required for payout-level reconciliation: arrival date, status, failure reason, destination
* **Setup Intents** (setup\_intent\_read) — Required to retrieve SetupIntent objects for stored-card flows
* **Reporting - Write:**
* **Financial Reports** (report\_runs\_and\_report\_types\_write) — Required to generate new reports on your behalf
7. Click **Create key**
8. Complete the 2FA verification if prompted
9. **Copy the key** (it will start with `rk_live_...`) and store it securely. You will not be able to view it again
### Step 2: Generate your Sandbox (Test Mode) Key
1. In the Stripe Dashboard, switch the **Test mode** toggle to **ON**
2. Navigate to **Developers** > **API keys**
3. Under the "Restricted keys" section, click **Create restricted key**
4. Name the key: `Payrails Sandbox Reporting`
5. Configure the **same permissions** as the Live key (see above)
6. Click **Create key**
7. **Copy the key** (it will start with `rk_test_...`) and store it securely
### Step 3: Add the Stripe integration in the Payrails portal (self-serve)
1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In New instance, select provider: **Stripe** and click **Continue**.
4. On the **Configure account** screen, fill in:
* **Integration instance name** — a unique label.
* **Start Date** — the date of today or tomorrow (currently we can not backfill over the sel-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
* **Is Live** — enable for the Live key; leave off for the Test/Sandbox key.
* **API key** — the restricted key: `rk_live_...` for production, `rk_test_...` for sandbox. Create a separate instance for each environment.
* *(Optional)* **Additional data**.
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.
## Related topics
- [Stripe](/docs/orchestration/integrations/stripe.md)
- [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk.md)
- [iDEAL](/docs/orchestration/payment-methods/ideal.md)