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.
Auth model
Section titled “Auth model”- Stripe Connect (
oauth2, recommended for multi-tenant SaaS). Authorisation-code flow athttps://connect.stripe.com/oauth/authorize, exchange athttps://connect.stripe.com/oauth/token. Returnsaccess_token+refresh_token+stripe_user_id(the connected account’sacct_…). - Secret API key (
api_key, single-merchant deploys). Submit ask_live_…orsk_test_…directly through the Connect Link form. The adapter will treat the key as the bearer token; no refresh is required.
Prerequisites
Section titled “Prerequisites”- A Stripe account at https://dashboard.stripe.com.
- For Connect: register a Connect application under Settings → Connect → Settings. Note the
client_id(ca_…), the platform secret key, and add your callback URL. - For direct API-key deploys: nothing — just copy the secret key from Developers → API keys.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Payments, click Stripe. - Fill Configure:
clientId— your Connectclient_id(skip for direct-API-key mode).clientSecret— your platform secret key (sk_live_…orsk_test_…).redirectUri—${PUBLIC_BASE_URL}/auth/payments/stripe/callback.
- Enable the adapter. End-users then connect via
/connect-linkor your direct redirect.
Required scopes
Section titled “Required scopes”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.
Webhooks
Section titled “Webhooks”- Add an endpoint at
https://${PUBLIC_BASE_URL}/webhooks/stripe. - Subscribe to:
charge.*,payment_intent.*customer.*,customer.subscription.*invoice.*,invoiceitem.*payout.*charge.dispute.*
- 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.
Sandbox / test mode
Section titled “Sandbox / test mode”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.
Quirks worth knowing
Section titled “Quirks worth knowing”- 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_methodsis customer-scoped. Pass?customer_id=cus_…onGET /v1/payments/payment_methods— Stripe has no global “list all PaymentMethods” endpoint.- Cancellation semantics.
POST /v1/payments/charges/:id/cancelvoids an uncaptured authorisation. Already-captured charges must be refunded viaPOST /v1/payments/refunds. atPeriodEndon subscription cancel setscancel_at_period_end=trueinstead of issuing the immediate-cancelDELETE /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.
References
Section titled “References”- Stripe API reference: https://docs.stripe.com/api
- Connect OAuth: https://docs.stripe.com/connect/oauth-reference
- Webhooks: https://docs.stripe.com/webhooks
- Webhook signatures: https://docs.stripe.com/webhooks/signatures
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.