Skip to main content
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

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 Stripe dashboard with test mode toggle off
  3. Navigate to Developers > API keys Stripe developers API keys page
  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
Stripe dashboard with test mode toggle on
  1. Navigate to Developers > API keys
  2. Under the “Restricted keys” section, click Create restricted key
  3. Name the key: Payrails Sandbox Reporting
  4. Configure the same permissions as the Live key (see above)
  5. Click Create key
  6. 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.
Last modified on November 13, 2026