GuidesTutorial

Verify Stripe Checkout safely

Use Stripe test mode to validate a real purchase path without a real card.

Guides

Verify Stripe Checkout without a real credit card

You do not need a customer card to prove your launch billing path works. PreFlight's Stripe Shadow Check runs a synthetic test-mode Checkout session, verifies webhook delivery, and confirms the Supabase side effect landed — end to end.

Shadow mode uses Stripe test keys only (sk_test_…). It creates a real hosted Checkout session, waits for payment completion, then polls your mapped Supabase table for the fulfillment row your webhook handler should write.

What success proves

| Stage | Probe | Proves | | --- | --- | --- | | Session creation | `stripe_shadow_checkout_start` | Checkout session and hosted URL are valid | | Payment | `stripe_shadow_checkout_payment` | Session reached paid in Stripe | | Side effect | `supabase_shadow_side_effect` | Expected row exists in mapped table/column |

A passing shadow run validates the same path Payment Sync reconciles in production.

Prerequisites

Recommended workflow

Use Stripe test mode. Create a reusable test Price in Stripe Dashboard. Save the secret key, webhook signing secret, and webhook URL in PreFlight's Stripe integration. Configure verification fields. Set testPrices to an explicit JSON array of {`{ key, label, priceId, mode }`} entries. Use mode: "payment" for one-time Prices and mode: "subscription" for recurring Prices. The legacy priceId field remains a single default payment plan. Optionally set verifyTableName, verifyTraceColumn, verifyStatusColumn, verifyExpectedStatus, verifyCreatedAtColumn, and verifyWindowSeconds for async handlers. Start the shadow run. From Checks or via API, call shadow/start. PreFlight returns a hosted checkoutUrl and traceId. Complete Checkout with test credentials. Open the hosted URL and pay with Stripe test card 4242 4242 4242 4242 (any future expiry, any CVC). No real card is charged. Finalize the run. Call shadow/finalize (or use the dashboard action). PreFlight verifies payment status and polls Supabase until the side effect appears or the window expires. For mode: "subscription", PreFlight creates an initial recurring Checkout, propagates the trace and plan metadata through subscription_data.metadata, and verifies the first paid session plus the same Supabase fulfillment row. Renewal, cancellation, dunning, refunds, trials, coupons, and taxes are outside this happy-path check. Shadow checks reject live secret keys. Use test mode end to end, then repeat provider checks with production credentials before opening signups.

Dashboard flow

Open Revenue → Checkout test for the project.
Ensure Stripe and Supabase integrations show connected and at least one explicit test plan is configured.
Select a plan, then start the checkout test. The dashboard keeps the plan label, key, Price ID, mode, trace, and Checkout session attached to the run.
Complete the hosted Checkout session in the new browser tab, or use the Stripe test card shown by the runner.
Leave the page open or return later; PreFlight polls Stripe and verifies the database side effect automatically. Review the receipt and per-plan history when it settles.

API flow (CI and preview deploys)

Shadow endpoints are documented separately from API v1 because they are Stripe-specific:

Creates a test-mode Checkout session. Optional body: previewUrl, priceKey, source. Omit priceKey to run the first/default configured plan. Scheduled Revenue Guard runs every configured plan automatically. Send Idempotency-Key from CI so retries reuse the same selected-plan run. Verifies payment and waits for the Supabase side effect. Body: runId, traceId, checkoutSessionId.

Example start response:

{
  "runId": "uuid",
  "status": "running",
  "traceId": "pf_trace_…",
  "checkoutSessionId": "cs_test_…",
  "checkoutUrl": "https://checkout.stripe.com/…",
  "priceKey": "pro-monthly",
  "priceLabel": "Pro monthly",
  "priceId": "price_…",
  "checkoutMode": "subscription"
}

PreFlight embeds preflight_trace_id in Checkout session metadata and client_reference_id so your webhook handler can write the same trace to Supabase.

Autonomous all-plan runs

Revenue Guard uses the same shadow-run orchestrator as the dashboard, but it does not choose only one plan. Each scheduled batch runs every entry in testPrices sequentially, so the existing one-active-shadow-run database guard stays safe. Each price consumes one unit from the shared synthetic-run meter and uses the same browser queue as Journey Canary. A browser or fulfillment failure for one plan is recorded with its label, trace, Price ID, and Checkout session, then the next configured plan still runs.

The dashboard lets an operator select one plan for a manual run. The history and receipt show the plan label, checkout mode, Price ID, trace ID, and session ID so a multi-plan batch is diagnosable without opening raw logs.

Mapping discovery

If the saved mapping misses during a shadow run, PreFlight attempts discovered trace-bearing tables from the connected Supabase OpenAPI schema before failing. Still, explicit mapping is recommended — discovery is a fallback, not a substitute for knowing your schema.

Common failures

| Symptom | Likely cause | Fix | | --- | --- | --- | | Checkout never creates | Wrong key, invalid Price ID, or blocked preview URL | Confirm the sk_test_ key and the selected testPrices entry; set previewUrl to a reachable origin | | Payment succeeds, DB fails | Webhook route or trace mapping wrong | Check handler logs for the traceId; align verifyTraceColumn | | Verification window expires | Async side effect too slow | Increase verifyWindowSeconds or optimize webhook handler | | Shadow start rate limited | More than 4 starts/minute per project | Use Idempotency-Key in CI to reuse existing runs | The table and column you map for shadow verification should match Payment Sync reconciliation. One correct mapping validates both launch rehearsal and ongoing drift detection.