API reference

Shadow Stripe flow

Shadow mode is the Stripe-specific automation path for validating a real test-mode Checkout session and proving the expected database side effect occurred. It lives outside API v1 because the workflow is provider-specific and interactive.

Use shadow runs for CI preview verification, launch rehearsal, and debugging webhook-to-database propagation. Requires test-mode Stripe keys and a mapped Supabase verification table.

Endpoints

Creates a test-mode Checkout session and returns a hosted payment URL. Verifies the session reached paid and polls Supabase for the mapped side effect.

Authentication uses the same bearer API keys as API v1 (Authorization: Bearer pf_live_…).

Request and response

Start

POST /api/projects/:projectId/shadow/start
Authorization: Bearer pf_live_...
Content-Type: application/json
Idempotency-Key: ci-preview-123

{
  "previewUrl": "https://preview.example.com",
  "source": "github_action"
}

Field	Required	Description
previewUrl	No	Base URL for success/cancel redirects when not set on integration
source	No	api or github_action — stored on the check run for audit

Response:

{
  "runId": "uuid",
  "status": "running",
  "traceId": "pf_trace_…",
  "checkoutSessionId": "cs_test_…",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/…"
}

Finalize

POST /api/projects/:projectId/shadow/finalize
Authorization: Bearer pf_live_...
Content-Type: application/json

{
  "runId": "uuid",
  "traceId": "pf_trace_…",
  "checkoutSessionId": "cs_test_…"
}

Response on success:

{
  "runId": "uuid",
  "traceId": "pf_trace_…",
  "status": "success",
  "stage": "supabase_side_effect",
  "message": "Shadow checkout verified end to end."
}

Failed responses include stage (stripe_payment or supabase_side_effect) and probe-level details for triage.

When to use it

| Scenario | Why shadow mode | | --- | --- | | CI preview verification | Prove billing path on every PR deploy without manual card entry | | Launch rehearsal | Walk through pricing flow before opening signups | | Webhook debugging | Isolate whether failure is Stripe, webhook, or Supabase write | | Payment Sync setup | Confirm mapping before enabling production reconciliation |

Required Stripe integration fields

Configure these on the project's Stripe integration before starting a shadow run:

| Field | Purpose | | --- | --- | | `priceId` | Stripe Price used for the synthetic Checkout line item | | `verifyTableName` | Supabase table where fulfillment rows appear | | `verifyTraceColumn` | Column containing the trace ID your webhook writes |

PreFlight can scan the connected Supabase OpenAPI schema and suggest the strongest mapping. If the saved mapping misses during a run, verification also attempts discovered trace-bearing tables before failing.

Optional verification fields

| Field | Purpose | | --- | --- | | `verifyStatusColumn` | Column that must match expected status | | `verifyExpectedStatus` | Expected value (e.g. `active`, `paid`) | | `verifyCreatedAtColumn` | Timestamp column for recency validation | | `verifyWindowSeconds` | How long finalize polls for async side effects | | `previewUrl` | Default base URL for redirect URLs | | `successUrl` / `cancelUrl` | Override Checkout redirect targets |

Trace ID propagation

PreFlight generates a pf_trace_… ID and embeds it in:

• Checkout session metadata.preflight_trace_id
• client_reference_id
• Payment intent metadata

Your webhook handler should persist the same trace value to verifyTraceColumn so finalize and Payment Sync can find the row.

Idempotency

Send an Idempotency-Key header on shadow/start from CI. If the deploy job retries, PreFlight returns the existing shadow run and Checkout URL instead of creating a second session.

Daily start limits apply per project (SHADOW_START_LIMIT_PER_DAY). Use idempotency to avoid exhausting the budget on flaky pipelines.

Rate limits

| Bucket | Limit | | --- | --- | | Auth fingerprint | 40 requests / minute | | Per project | 4 starts / minute | Shadow start rejects secret keys that do not start with sk_test_. Live keys cannot be used for synthetic Checkout sessions.

Probe timeline

Each shadow run writes deterministic probe rows:

| Probe key | Stage | | --- | --- | | `stripe_shadow_checkout_start` | Session created | | `stripe_shadow_checkout_payment` | Payment verified in Stripe | | `supabase_shadow_side_effect` | Row found in mapped table |

Inspect these in Checks → run timeline or via GET /api/v1/projects/:id/checks/:runId.

Shadow endpoints remain fully supported but are documented separately from the standardized public API because they are Stripe-specific and workflow-specific. Automation that only needs pass/fail should still read check run status from API v1.

<RelatedLinks links={[ { href: "/docs/guides/verify-stripe-checkout-without-a-real-credit-card", title: "Verify Checkout without a card", description: "Step-by-step dashboard and test card workflow." }, { href: "/docs/guides/revenue-watch", title: "Payment Sync", description: "Production reconciliation using the same mapping." }, { href: "/docs/integrations/stripe", title: "Stripe integration", description: "Webhook and verify field setup." }, { href: "/docs/api/authentication", title: "API authentication", description: "Bearer keys and idempotency headers." }, ]} />