Skip to content

Integrating Stripe

Auth: OAuth 2.0 · Partner program: not required · Setup time: about 15 minutes · Last verified: 2026-05-15

Stripe is the reference implementation for the payments vertical. It exposes the full canonical surface — customers, payment methods, charges, refunds, subscriptions, invoices + line items, payouts, disputes, plans, prices, products, balance transactions — and is the model every other payments adapter is measured against.

  • Stripe Connect (oauth2, recommended for multi-tenant SaaS). Authorisation-code flow at https://connect.stripe.com/oauth/authorize, exchange at https://connect.stripe.com/oauth/token. Returns access_token + refresh_token + stripe_user_id (the connected account’s acct_…).
  • Secret API key (api_key, single-merchant deploys). Submit a sk_live_… or sk_test_… directly through the Connect Link form. The adapter will treat the key as the bearer token; no refresh is required.
  1. A Stripe account at https://dashboard.stripe.com.
  2. For Connect: register a Connect application under Settings → Connect → Settings. Note the client_id (ca_…), the platform secret key, and add your callback URL.
  3. For direct API-key deploys: nothing — just copy the secret key from Developers → API keys.
  1. Open /platforms in the admin UI, filter to Payments, click Stripe.
  2. Fill Configure:
    • clientId — your Connect client_id (skip for direct-API-key mode).
    • clientSecret — your platform secret key (sk_live_… or sk_test_…).
    • redirectUri — ${PUBLIC_BASE_URL}/auth/payments/stripe/callback.
  3. Enable the adapter. End-users then connect via /connect-link or your direct redirect.

The default is read_write, which permits every API call against the connected account. Override per-installation if you need a stricter set; Stripe’s permission model is coarse-grained at the Connect level, so most operators keep the default.

  1. Add an endpoint at https://${PUBLIC_BASE_URL}/webhooks/stripe.
  2. Subscribe to:
    • charge.*, payment_intent.*
    • customer.*, customer.subscription.*
    • invoice.*, invoiceitem.*
    • payout.*
    • charge.dispute.*
  3. Copy the signing secret (whsec_…) into the adapter’s webhook secret setting.

The adapter verifies the Stripe-Signature header (HMAC-SHA256 of ${t}.${body} with a 5-minute timestamp tolerance) and parses every event into a canonical WebhookEvent. Event types map to {resourceType, action} automatically — charge.succeeded → {charges, succeeded}, invoice.finalized → {invoices, finalized}, and so on.

Use a test-mode secret key (sk_test_…) or a test-mode Connect application. Test-mode credentials issue the same token shape as live keys, and the adapter treats them identically — livemode is exposed in credentials.extra.livemode if you need to branch on it.

  • Money is integer minor units. Stripe always uses minor units (cents, paise, satoshi …); the adapter passes them through unchanged. No float conversion.
  • customers.list_payment_methods is customer-scoped. Pass ?customer_id=cus_… on GET /v1/payments/payment_methods — Stripe has no global “list all PaymentMethods” endpoint.
  • Cancellation semantics. POST /v1/payments/charges/:id/cancel voids an uncaptured authorisation. Already-captured charges must be refunded via POST /v1/payments/refunds.
  • atPeriodEnd on subscription cancel sets cancel_at_period_end=true instead of issuing the immediate-cancel DELETE /subscriptions/:id. Use it to honour the customer’s remaining paid period.
  • Tier-2 coverage is first-class on Stripe. Plans, Prices, Products, and BalanceTransactions are full transforms here — other adapters skip them.