Stripe Rail

Overview

The Stripe rail supports three payment modes:

Invoice payment — recipient is a Stripe invoice ID (in_xxx) → calls POST /v1/invoices/{id}/pay
PaymentIntent confirmation — recipient is a PaymentIntent ID (pi_xxx) → calls POST /v1/payment_intents/{id}/confirm
Payment link — recipient is a Stripe payment link (plink_xxx) → returns the link for human completion (semi-autonomous)

Best for: SaaS subscriptions, Cloudflare invoices, Anthropic billing, and any merchant accepting Stripe.

Setup

STRIPE_SECRET_KEY=sk_live_...
STRIPE_ENV=live   # or 'test' for sandbox (default)

Usage

Pay a Stripe invoice by ID

The most common pattern for autonomous agent payments — the agent receives an invoice ID and pays it directly:

const result = await executeAgentPayment(signed, {
  recipient: 'in_1Pxyz123abc',   // Stripe invoice ID
  amount: 47.20,
  rail: 'stripe',
  memo: 'Cloudflare April invoice',
})

console.log(result.success)    // true
console.log(result.txId)       // 'pi_1Pxyz123abc...' (PaymentIntent ID)
console.log(result.rail)       // 'stripe'

The rail fetches the invoice to verify the amount against the envelope’s maxAmount before paying. If the invoice amount exceeds the envelope cap, the payment is rejected before any charge is made.

Confirm a PaymentIntent

When you’ve already created a PaymentIntent and need to confirm it:

const result = await executeAgentPayment(signed, {
  recipient: 'pi_3Qxyz456def',   // Stripe PaymentIntent ID
  amount: 25.00,
  rail: 'stripe',
})

Mock mode (development)

Set PQSAFE_MOCK_MODE=1 to run in mock mode — no real Stripe API calls, returns a simulated pi_sbx_... transaction ID. Safe for integration testing without a Stripe account.

Environment variables

Variable	Required	Description
`STRIPE_SECRET_KEY`	Yes	Stripe secret key (`sk_live_...` or `sk_test_...`)
`STRIPE_ENV`	No	`live` or `test` (default: `test`)
`PQSAFE_MOCK_MODE`	No	Set to `1` to skip real API calls

Error codes

Code	Cause	Fix
`CARD_DECLINED`	Stripe card network declined	Check card expiry, limit, 3DS
`INVOICE_ALREADY_PAID`	Invoice was already paid	No action needed
`INSUFFICIENT_FUNDS`	No funds on payment method	Add funds or use a different payment method

→ ACP Adapter (Stripe) — Stripe Agent Commerce Protocol integration
→ Recipe: Pay Cloudflare Invoice — full end-to-end example
→ Rails concept page — cross-rail comparison