Stripe

This guide will help you generate the necessary API credentials to ingest financial reports and transaction data from Stripe into your Payrails account.

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

   

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: Share credentials with Payrails

Share your API credentials in a secured way with Payrails. Please clearly label which key is for Live and which is for Sandbox.

Recommended methods:

• Use your preferred secrets manager or vault tool (1Password Shared Vaults, AWS Secrets Manager, or GCP Secrets Manager)
• If a shared vault is not possible, share credentials over a PGP-encrypted file