Billing Live Rehearsal

Scope: NyrA Swarm Little Buddy paid beta.

This is the guarded path for proving the Stripe Checkout, Customer Portal, webhook, backend, and desktop license activation flow before any public paid launch.

This is not legal, tax, accounting, or Stripe support advice. Use Stripe test mode first. Do not run live mode until business identity, tax, support, policies, domain, and attorney/accountant review are complete.

Why This Exists

The app already has:

• Stripe Checkout session creation.
• Stripe Customer Portal session creation.
• Webhook event handling.
• Checkout-session device activation.
• Device-scoped access token.
• Paid feature entitlement gate.
• Offline grace metadata.

The remaining risk is operational: live secrets, URLs, Customer Portal settings, webhook settings, price/cap decisions, and support/legal readiness must all be true at the same time.

Commands

Run preflight in test mode:

npm run billing:live-preflight -- --mode test

Run hosted rehearsal after backend deployment:

$env:NYRA_BILLING_BASE_URL = "https://billing.your-domain.example"
$env:NYRA_REHEARSAL_EMAIL = "your-test-email@example.com"
npm run billing:live-rehearsal -- --mode test

Create a test Checkout Session only when you are ready:

$env:NYRA_BILLING_REHEARSAL_EXECUTE = "true"
npm run billing:live-rehearsal -- --mode test
Remove-Item Env:\NYRA_BILLING_REHEARSAL_EXECUTE

Live mode has an extra guard:

$env:NYRA_ALLOW_LIVE_BILLING_REHEARSAL = "true"
npm run billing:live-preflight -- --mode live
Remove-Item Env:\NYRA_ALLOW_LIVE_BILLING_REHEARSAL

Required Stripe Setup

Use Stripe Billing subscriptions with Stripe-hosted Checkout and Customer Portal.

Required webhook events:

• checkout.session.completed
• invoice.paid
• invoice.payment_failed
• customer.subscription.updated
• customer.subscription.deleted

Recommended event:

• entitlements.active_entitlement_summary.updated

Required Command-Center Decisions

• Monthly price saved.
• Hosted AI cap saved.
• Support inbox confirmed after ticket roundtrip.
• Domain/backend URL chosen.
• Business name or entity path saved.
• Customer Portal configured.
• Attorney/accountant review approved before live payments.
• Deployability preflight no longer reports NO_GO_LIVE_MONEY.
• Release candidate preflight reports paid beta allowed, not INTERNAL_ALPHA_ONLY.

Required Secret Store Values

These belong in the deployment provider secret store or temporary shell only, never in repo files:

• STRIPE_SECRET_KEY - use a least-privilege restricted server key (rk_test_ / rk_live_) when its permissions cover NyrA Billing; keep it in the deployment secret store
• STRIPE_WEBHOOK_SECRET
• NYRA_STRIPE_PRICE_PRO_MONTHLY
• NYRA_BILLING_SUCCESS_URL
• NYRA_BILLING_CANCEL_URL
• NYRA_BILLING_RETURN_URL
• NYRA_LICENSE_API_TOKEN
• NYRA_LICENSE_SIGNING_SECRET

Stop Conditions

Stop the rehearsal and keep checkout disabled if:

• Any secret appears in a repo file or command-center state.
• Customer Portal cancellation is not enabled.
• Webhook endpoint is not verified.
• Desktop activation does not receive an active signed license after test checkout.
• Canceled or failed subscriptions do not revoke paid features.
• Support inbox cannot receive and answer a test ticket.
• Policies do not match actual checkout, refund, cancellation, AI usage, privacy, or support behavior.
• Deployability still has P0 blockers or the release candidate is still internal-alpha only.

Sources

• Stripe go-live checklist: https://docs.stripe.com/get-started/checklist/go-live
• Stripe testing use cases: https://docs.stripe.com/test-mode
• Stripe subscription webhooks: https://docs.stripe.com/billing/subscriptions/webhooks
• Stripe Customer Portal integration: https://docs.stripe.com/customer-management/integrate-customer-portal