Appearance
ADR 0010: Stripe Checkout for payments
Status: Accepted. Supersedes ADR 0006.
Context
ADR 0006 deferred payments and named Polar as the provider. The milestone that needs payments now lands. Payment belongs to a lead before any client account exists, and to an invoice once the client is billed. The manual "record payment" fallback must keep running the same path.
Decision
Use Stripe Checkout through its REST API, with no SDK:
- One Checkout Session per payment subject (lead or invoice) and amount. The
idempotency-keyheader iskind-subjectId-amountPence, so a retry returns the same session. - The session is created in
paymentmode, priced in GBP, withmetadatacarryingleadIdorinvoiceId, the expected amount in pence and the currency. POST /webhooks/stripeverifies theStripe-Signatureheader with HMAC-SHA256 through Web Crypto (Workers compatible), refuses deliveries older than 5 minutes, and records each event id once in the audit log.- Only
checkout.session.completedandcheckout.session.async_payment_succeededwithpayment_status: "paid"settle anything. The paid amount must equal the expected amount exactly. Otherwise nothing is marked paid, the owners are notified, and apayment.mismatchaudit row is written. - Payments made through Stripe are stored with method
stripe. Manual payments keep methodmanualand run the samemarkPaid/markInvoicePaidfunctions. STRIPE_SECRET_KEYandSTRIPE_WEBHOOK_SECRETare optional. Without them no link is created (the owner sees "not configured") and the webhook answers 503.
Consequences
- No Polar packages or environment variables remain. The Polar SDK is not needed.
- The provider sits behind
PaymentProviderinpackages/api/src/integrations, so tests use a stub and the app runs without keys. - Invoice links are stored on the invoice (
payment_url) and reissued only while nothing has been paid. - Client billing shows a Pay button on sent or overdue invoices that have a link.