Skip to content

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-key header is kind-subjectId-amountPence, so a retry returns the same session.
  • The session is created in payment mode, priced in GBP, with metadata carrying leadId or invoiceId, the expected amount in pence and the currency.
  • POST /webhooks/stripe verifies the Stripe-Signature header 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.completed and checkout.session.async_payment_succeeded with payment_status: "paid" settle anything. The paid amount must equal the expected amount exactly. Otherwise nothing is marked paid, the owners are notified, and a payment.mismatch audit row is written.
  • Payments made through Stripe are stored with method stripe. Manual payments keep method manual and run the same markPaid / markInvoicePaid functions.
  • STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are 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 PaymentProvider in packages/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.

Internal documentation. Not for clients.