Implement the Stripe billing adapter #2

New issue

Open

opened 2026-08-25 10:53:22 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 10:53:22 +00:00

(Migrated from github.com)

Goal

Implement Stripe as the first payment-provider adapter over the provider-neutral billing core in #1.

Boundary

Stripe handles payment methods, hosted payment UX where appropriate, payment processing, and provider-side lifecycle. starintel-biz remains authoritative for normalized StarIntel billing/subscription state.

Requirements

Re-check the current Stripe API/webhook model at implementation time; pin an explicit API version rather than inheriting accidental account defaults.
Model StarIntel product/plan/price mappings explicitly and keep provider IDs as external references, not the domain model itself.
Prefer Stripe-hosted/Elements-style payment collection so raw card data never traverses StarIntel servers unless a separately reviewed requirement demands it.
Verify webhook signatures against the exact raw request body before parsing/mutation.
Persist provider event IDs and make duplicate webhook delivery idempotent.
Correctly handle asynchronous/out-of-order events for checkout/payment intent/invoice/subscription lifecycle, failures, cancellation, refunds, disputes/reversals, and retries as applicable to the chosen Stripe flow.
Never trust a browser redirect/success page as payment proof; canonical state changes come from verified provider data/events and explicit reconciliation.
Add bounded API timeouts, retries only for safe/idempotent operations, idempotency keys on Stripe mutations, rate-limit handling, and reconciliation jobs for missed events.
Stripe API/webhook secrets come from runtime credentials only and must never appear in Git, logs, Nix store, responses, or client bundles.
Emit normalized provider/audit events into the #1 billing event path with secret/payload minimization.

Webhook integration

Integrate through the generic StarIntel webhook ingress where that architecture is appropriate, while preserving raw-body signature verification and a narrow normalized dispatch contract. Do not allow a generic webhook route to bypass Stripe verification.

Tests / acceptance

signed fixture event accepted; bad signature rejected
duplicate/out-of-order event fixtures converge to the same canonical state
successful purchase/renewal/failure/cancel/refund/dispute flows map into #1 correctly
redirect without verified payment does not grant paid state
API timeout/rate-limit retry behavior is bounded
no card data or secrets enter logs/test snapshots
exact-head integration tests pass against Stripe test-mode fixtures/API where available

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: re-check current Stripe docs/API first; inspect #1 and StarIntel webhook/account boundaries; design and record the adapter/event mapping; adversarial review + payment-fraud/replay/idempotency/secret threat model; autonomous decision gate; TDD-first implementation; exact-head test-mode/fixture verification; push a focused branch and open/update a PR targeting main. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Implement Stripe as the first payment-provider adapter over the provider-neutral billing core in #1. ## Boundary Stripe handles payment methods, hosted payment UX where appropriate, payment processing, and provider-side lifecycle. `starintel-biz` remains authoritative for normalized StarIntel billing/subscription state. ## Requirements - Re-check the current Stripe API/webhook model at implementation time; pin an explicit API version rather than inheriting accidental account defaults. - Model StarIntel product/plan/price mappings explicitly and keep provider IDs as external references, not the domain model itself. - Prefer Stripe-hosted/Elements-style payment collection so raw card data never traverses StarIntel servers unless a separately reviewed requirement demands it. - Verify webhook signatures against the exact raw request body before parsing/mutation. - Persist provider event IDs and make duplicate webhook delivery idempotent. - Correctly handle asynchronous/out-of-order events for checkout/payment intent/invoice/subscription lifecycle, failures, cancellation, refunds, disputes/reversals, and retries as applicable to the chosen Stripe flow. - Never trust a browser redirect/success page as payment proof; canonical state changes come from verified provider data/events and explicit reconciliation. - Add bounded API timeouts, retries only for safe/idempotent operations, idempotency keys on Stripe mutations, rate-limit handling, and reconciliation jobs for missed events. - Stripe API/webhook secrets come from runtime credentials only and must never appear in Git, logs, Nix store, responses, or client bundles. - Emit normalized provider/audit events into the #1 billing event path with secret/payload minimization. ## Webhook integration Integrate through the generic StarIntel webhook ingress where that architecture is appropriate, while preserving raw-body signature verification and a narrow normalized dispatch contract. Do not allow a generic webhook route to bypass Stripe verification. ## Tests / acceptance - signed fixture event accepted; bad signature rejected - duplicate/out-of-order event fixtures converge to the same canonical state - successful purchase/renewal/failure/cancel/refund/dispute flows map into #1 correctly - redirect without verified payment does not grant paid state - API timeout/rate-limit retry behavior is bounded - no card data or secrets enter logs/test snapshots - exact-head integration tests pass against Stripe test-mode fixtures/API where available ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: re-check current Stripe docs/API first; inspect #1 and StarIntel webhook/account boundaries; design and record the adapter/event mapping; adversarial review + payment-fraud/replay/idempotency/secret threat model; autonomous decision gate; TDD-first implementation; exact-head test-mode/fixture verification; push a focused branch and open/update a PR targeting `main`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

lost-rob0t commented

2026-08-25 10:58:46 +00:00

(Migrated from github.com)

Stripe architecture, API/version policy, event mapping, webhook verification, reconciliation, test-mode usage, secret rotation, and outage/recovery docs are tracked in #5. Keep those docs synchronized with this adapter as it lands.