Stripe test-mode example (Pro)

This module demonstrates subscription billing inside a SaaS built from Pro. It does not sell or deliver this starter kit. The landing page checkout is separately configured.

Set STRIPE_SECRET_KEY to your own test key, STRIPE_PRICE_ID to a recurring test price and STRIPE_WEBHOOK_SECRET to the webhook endpoint secret. Leave them blank to keep the integration unavailable. Never use live keys here. The server selects the price and callback URLs; the browser cannot submit arbitrary prices or redirects.

After authentication, checkout and portal endpoints return a Stripe URL. Subscription status is updated by verified events, not by visiting the success page. The customer is mapped to the current application user. Replayed events must not apply the change twice.

Use the Stripe CLI in your own test account:

stripe listen --forward-to localhost:8081/api/billing/webhook

Copy the CLI's signing secret into ignored local configuration and restart the API. Complete checkout with Stripe's documented test payment data. Verify the subscription endpoint and portal against the same user. Test duplicate delivery, invalid signatures and cancellation before adapting this example.

Webhook verification requires the raw request body, the Stripe-Signature header and the matching endpoint secret. Stripe signature documentation. The CLI and Dashboard can issue different webhook signing secrets.

Live billing, taxes, invoices, refunds, dunning, production event ordering and entitlement design require additional implementation and provider-level tests. A passing signature unit test does not prove a working account integration. If no credentials are supplied, checkout and portal remain explicitly unavailable and are reported as unverified.

Source: docs/starter-kit/stripe.md · Included with the starter kit.