Configure credit purchases

This operator guide describes the implemented one-time checkout candidate. Billing stays off until the required terms/rates, refund/dispute handling and real provider acceptance are complete. No prices are chosen by this guide. Public site deploys do not configure Stripe, migrate Supabase or deploy the API. Keep development/test and live deployments separate.

1. Prepare configuration

1. Apply current migrations, including 20261013000002_checkout.sql, to the intended environment.

2. Measure costs and approve the credit service schedule and pack entitlement. Create a fixed one-time USD Stripe price for that approved offer; do not copy speculative spec prices.

3. Store ALIVE_STRIPE_SECRET_KEY and ALIVE_STRIPE_WEBHOOK_SECRET in the deployment secret store. Never commit them or place them in a frontend NEXT_PUBLIC_ variable.

4. Configure ALIVE_CREDIT_PACKS as a JSON array, with actual approved values:

   [{"key":"approved-pack","title":"Approved compute pack","price_id":"price_REPLACE","credits":100}]

   100 is an illustrative entitlement, not a recommended allowance or monetary price.

5. Set ALIVE_BILLING_RETURN_URL to the intended app's /settings URL. Program purchases also return there; the saved owner-specific intent remains inspectable. Redirects cannot be supplied by API callers. Set ALIVE_STRIPE_LIVE_MODE to the environment's actual mode.

6. Configure a Stripe snapshot webhook to https://YOUR_API/v1/billing/stripe/webhook, API version 2026-09-30.endive, for the four events in the reference. Test locally using Stripe's documented CLI forwarding, with the forwarding listener's signing secret rather than a different destination.

7. Enable only a reviewed test environment initially. ALIVE_ENVIRONMENT=production rejects test-mode activation. Production activation requires the remaining live acceptance/approval.

2. Exercise the configured test environment

Sign in as an organization owner/admin. Fetch the pack catalog, start a checkout with a saved key, complete it using Stripe's documented test payment methods and inspect the recorded intent:

curl "$ALIVE_API_URL/v1/billing/packs" -H "Authorization: Bearer $ALIVE_SESSION_TOKEN"
curl "$ALIVE_API_URL/v1/billing/checkout" \
  -H "Authorization: Bearer $ALIVE_SESSION_TOKEN" \
  -H "Idempotency-Key: $ALIVE_PURCHASE_KEY" -H 'Content-Type: application/json' \
  --data "{\"org_id\":\"$ALIVE_ORG_ID\",\"pack_key\":\"approved-pack\"}"
curl "$ALIVE_API_URL/v1/billing/purchases/$ALIVE_INTENT_ID" \
  -H "Authorization: Bearer $ALIVE_SESSION_TOKEN"

These commands require a configured test deployment and user session; they are not CI snippets and this documentation does not execute a payment. Use actual recorded IDs/keys, not placeholders. Confirm one ledger issuance, duplicate deliveries, delayed/unpaid payments, failures, expired links, invalid signatures, owner isolation and program funding without recipient allocation. Test-mode credits stay in the test database. Record observations before claiming provider acceptance.

3. Inspect/reconcile a missing callback

The maintainer command uses deployment secrets/database authority, not a public user token. It retrieves and verifies the recorded session. Inspection is the default; --apply uses the same once-only fulfillment path as the webhook.

python -m alive_api.reconcile_payments --session cs_RECORDED_SESSION
python -m alive_api.reconcile_payments --session cs_RECORDED_SESSION --apply

Check the command interface without credentials or a provider call:

uv run python -m alive_api.reconcile_payments --help > /dev/null

Resolve ambiguous sessions before starting another purchase. Reconciliation is not a cash-refund command, subscription implementation or a substitute for auditing provider totals against the purchase ledger. The command deliberately does not print provider/customer payloads.

Before real money

Finish paid-plan lifecycle, refund/dispute/chargeback entitlement handling and operational reconciliation; obtain Isaac's required billing/privacy/security approval; configure monitoring and retry/recovery ownership; run real Stripe test and authorized live acceptance. These are remaining M12 gates. The current code and mocked contract checks do not complete them.