docs(stripe): document test-mode subscription testing (BUNYIP-175) #206

Merged

longjacksonle merged 1 commit from docs/BUNYIP-175-stripe-test-mode into main

2026-06-24 01:40:17 +02:00

longjacksonle commented

2026-06-24 01:35:34 +02:00

Owner

What

Documents how to test membership subscriptions locally against Stripe test mode (BUNYIP-175). The original issue asked for a "sandbox environment"; the conclusion is that none is needed - Stripe's built-in test mode is the sandbox, and test cards only authorize against test-mode keys (rejected in live mode), so the flow cannot move real money.

Changes

dev-docs/stripe-test-mode.md (new): end-to-end walkthrough - load test-mode keys, forward webhooks with stripe listen --forward-to http://localhost:4401/v1/webhooks/stripe, map test products to tiers, drive the lifecycle, and the test-card table (4242... happy path, 4000...9995 / ...0341 / ...0002 failure paths). Includes cleanup and the verification steps that stay [needs test keys].
.env.example: add STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET to the dev section (they were only in the production secrets block) with comments pointing at the test-mode flow and the two load paths (env vs admin Stripe UI / stripe_config).

Webhook route confirmed (from source)

POST /v1/webhooks/stripe on port 4401 (bunyip-api/src/handlers/webhook.rs, mounted in routes/webhook.rs:9 + routes/mod.rs:24). Signature verified against STRIPE_WEBHOOK_SECRET, deduped on event.id. Six event types handled (checkout.session.completed, customer.subscription.{created,updated,deleted}, invoice.payment_{succeeded,failed}).

Scope

Docs and config only; no code paths change. The acceptance criteria that require a live subscribe / grace cycle / tier resolution stay gated on provisioned Stripe test-mode keys, matching the [needs test keys] items in dev-docs/billing-m1-implementation-plan.md.

🤖 Generated with Claude Code

## What Documents how to test membership subscriptions locally against Stripe **test mode** (BUNYIP-175). The original issue asked for a "sandbox environment"; the conclusion is that none is needed - Stripe's built-in test mode is the sandbox, and test cards only authorize against test-mode keys (rejected in live mode), so the flow cannot move real money. ## Changes - `dev-docs/stripe-test-mode.md` (new): end-to-end walkthrough - load test-mode keys, forward webhooks with `stripe listen --forward-to http://localhost:4401/v1/webhooks/stripe`, map test products to tiers, drive the lifecycle, and the test-card table (4242... happy path, 4000...9995 / ...0341 / ...0002 failure paths). Includes cleanup and the verification steps that stay `[needs test keys]`. - `.env.example`: add `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` to the dev section (they were only in the production secrets block) with comments pointing at the test-mode flow and the two load paths (env vs admin Stripe UI / `stripe_config`). ## Webhook route confirmed (from source) `POST /v1/webhooks/stripe` on port 4401 (`bunyip-api/src/handlers/webhook.rs`, mounted in `routes/webhook.rs:9` + `routes/mod.rs:24`). Signature verified against `STRIPE_WEBHOOK_SECRET`, deduped on `event.id`. Six event types handled (checkout.session.completed, customer.subscription.{created,updated,deleted}, invoice.payment_{succeeded,failed}). ## Scope Docs and config only; no code paths change. The acceptance criteria that require a live subscribe / grace cycle / tier resolution stay gated on provisioned Stripe test-mode keys, matching the `[needs test keys]` items in `dev-docs/billing-m1-implementation-plan.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

longjacksonle added 1 commit

2026-06-24 01:35:34 +02:00

docs(stripe): document test-mode subscription testing (BUNYIP-175)

E2E / Playwright against deployment (pull_request) Successful in 30s

Details

Check / fmt + clippy + build + tests (pull_request) Successful in 4m39s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

b5c0ab703e

Membership subscriptions could not be exercised end to end in dev because there was no payment path. The conclusion of BUNYIP-175 is that no separate sandbox environment is needed: Stripe's built-in test mode is the sandbox, since test cards authorize only against test-mode keys and are rejected in live mode.

Add `dev-docs/stripe-test-mode.md` walking through loading test-mode keys, forwarding webhooks to the local api with `stripe listen --forward-to http://localhost:4401/v1/webhooks/stripe`, mapping test products to tiers, and driving the lifecycle with the canonical test cards (4242... happy path, 4000...9995 / ...0341 / ...0002 failure paths).

Surface the dev Stripe env vars: add `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` to the dev section of `.env.example` (previously only the production secrets block mentioned them) with comments pointing at the test-mode flow and the two load paths (env vs admin Stripe UI / `stripe_config`).

Docs and config only; no code paths change. The remaining acceptance criteria (a live subscribe activating membership, the trigger-driven grace cycle, tier resolution from a mapped product) require provisioned Stripe test-mode keys and stay gated, matching the `[needs test keys]` items in the M1 plan.

#BUNYIP-175

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

longjacksonle scheduled this pull request to auto merge when all checks succeed

2026-06-24 01:37:14 +02:00