Payment Center

Stripe

Subscription, Customer Portal, webhook, billing backend deployment, and license activation command page.

Payment Launch Pack

Open pack

Use this pack as the exact money-path checklist before creating Stripe products, prices, webhook endpoints, or live checkout links.

Pack status Payment Launch Waiting On Handoffs Ready
Actions 22 Ready
Commands 10 Ready

Stripe Setup Runbook

Scope: NyrA Swarm Little Buddy desktop app only

This runbook is for the first paid launch path. It is not a substitute for tax, accounting, or legal advice.

Stripe Integration Choice

Use:

Do not:

Dashboard Setup

  1. Confirm Stripe account identity.
  2. Set public business name and branding.
  3. Create product:

- Name: NyrA Swarm Little Buddy Pro

- Type: subscription product

  1. Create monthly price:

- Currency: USD

- Amount: use the user-approved output from the command center Pricing page.

- Trial: none

  1. Configure Customer Portal:

- Enable invoice history.

- Enable payment method updates.

- Enable cancellation.

- Enable plan changes only after multiple plans exist.

  1. Configure Stripe Tax or document launch tax scope.
  2. Add webhook endpoint once backend URL exists.

Webhook Events

Minimum events to process:

Recommended when using Stripe Entitlements:

Backend Requirements

The payment/license backend needs:

Initial implementation files:

Validation command:

Local helper commands:

The setup tool dry-runs by default. It only creates Stripe resources with --execute.

Desktop Requirements

The Electron app needs:

The internal NYRA_LICENSE_API_TOKEN remains server-side only for admin/smoke checks. Customers should activate with checkout session + device token, not a shared API token.

Test Mode Checklist

Use docs/billing/BILLING_LIVE_REHEARSAL.md and the command-center Billing Rehearsal page for the guarded preflight before creating live payment paths.

Current Blockers

NyrA Billing Server

This is the first server-side payment and licensing service for the Swarm Little Buddy app.

It uses Stripe-hosted Checkout, Stripe Customer Portal, Stripe webhooks, and a local JSON entitlement store for early beta/dev wiring. Replace the JSON store with a real database before public launch.

The paid-beta JSON store now has atomic writes and /health runs a writable storage probe. In production or when NYRA_BILLING_REQUIRE_PERSISTENT_STORAGE=true, the server refuses to start unless NYRA_ENTITLEMENTS_FILE is set to an absolute mounted persistent path.

Commands

npm run billing:check
npm run billing:init-env
npm run billing:smoke
npm run test:billing-storage
npm run billing:stripe-setup -- --env server/.env.local
npm run billing:live-preflight -- --mode test
npm run billing:live-rehearsal -- --mode test
npm run billing:server
npm run test:billing-deploy
npm run test:billing-live-rehearsal

Local Config

Copy server/billing-config.example.env into your local secret manager or shell environment. Do not commit real Stripe keys.

Required values:

Routes

Customer checkout is public:

Customer license activation uses the paid checkout session plus the local device ID:

GET /api/license/status?checkoutSessionId=<cs_...>&deviceId=<device-id>

When active, the server returns a signed deviceAccessToken. Future license checks and Customer Portal requests use:

Authorization: Bearer <deviceAccessToken>

The internal NYRA_LICENSE_API_TOKEN is still available for server/admin smoke tests and controlled back-office checks. It should not be entered into the customer desktop app.

Deployment Pack

The backend now has a standalone deployment shape under server/:

Validate the deploy pack:

npm run test:billing-deploy
npm run test:billing-storage

Build locally when Docker is available:

docker build -f server/Dockerfile server -t nyra-billing-server:local

Do not deploy live mode until the command center has a monthly price, hosted AI cap, domain/backend URL, confirmed support inbox, Stripe identity/tax setup, Stripe product/price, Customer Portal configuration, webhook secret, and attorney/accountant review status.

Use docs/billing/BILLING_LIVE_REHEARSAL.md before live mode. It checks command-center decisions, required Stripe webhook events, Customer Portal/support/legal blockers, secret shapes, HTTPS URLs, and live-mode approval flags without printing secret values.

Current Limits

Desktop Activation Shell

The app Settings panel includes License & Billing.

Current device activation flow:

  1. Start the billing server.
  2. Enter the billing server URL and checkout email in Settings.
  3. Use Start Checkout to open Stripe Checkout.
  4. Use Refresh Activation after webhooks update entitlement state.
  5. The server exchanges the paid checkout session for a signed device access token.
  6. Use Billing Portal for subscription management after activation.

The desktop caches the signed license response and uses the server-provided offline grace timestamp if the billing server is temporarily unreachable.

Stripe Product/Price Tool

Dry run:

npm run billing:stripe-setup -- --env server/.env.local --price-cents 2500

Create or reuse product/price in the Stripe account:

npm run billing:stripe-setup -- --env server/.env.local --price-cents 2500 --execute

Create or reuse product/price and create a payment link:

npm run billing:stripe-setup -- --env server/.env.local --price-cents 2500 --execute --payment-link

Use test keys first. Do not use live keys until pricing, support email, tax setup, domain URLs, and policy pages are ready.

NyrA Billing Backend Deployment Checklist

Scope: NyrA Swarm Little Buddy paid beta only.

This service is the server-side Stripe Checkout, Customer Portal, webhook, and license activation backend. Stripe secret keys must stay here, never in Electron.

Deployable Shape

Build locally when Docker is available:

docker build -f server/Dockerfile server -t nyra-billing-server:local

Run locally with a private env file:

docker run --rm --env-file server/.env.local -p 8788:8788 nyra-billing-server:local

Do not commit .env.local, live Stripe keys, webhook secrets, signing secrets, or entitlement data.

Required Secret Store Values

Host Requirements

https://<billing-domain>/api/billing/webhook

Stripe Dashboard Steps

  1. Confirm business identity, payout, statement descriptor, and support details.
  2. Create NyrA Swarm Little Buddy Pro monthly subscription price after the monthly price is chosen.
  3. Configure Customer Portal for cancellation, payment method updates, and invoices.
  4. Add webhook endpoint after the backend public URL exists.
  5. Store the webhook signing secret in the deployment secret store.
  6. Test checkout, portal, cancellation, failed invoice, duplicate webhook, and desktop reactivation in Stripe test mode.
  7. Run the guarded rehearsal preflight before exposing any paid checkout link:
npm run billing:live-preflight -- --mode test

Go/No-Go

No live paid beta until these are true:

Rollback

If hosted billing fails during beta:

  1. Disable or pause the Stripe price.
  2. Remove the checkout CTA from the public launch site.
  3. Keep existing customers able to open Customer Portal.
  4. Preserve entitlement storage and logs.
  5. Announce support path and fix window through the support inbox.

Deployment Manifest

{
  "service": "nyra-billing-server",
  "scope": "NyrA Swarm Little Buddy paid beta billing and license activation",
  "runtime": "Node.js 24",
  "container": {
    "dockerfile": "server/Dockerfile",
    "buildContext": "server",
    "startCommand": "node nyra-billing-server.mjs",
    "portEnv": "NYRA_BILLING_PORT",
    "defaultPort": 8788,
    "healthCheck": "GET /health"
  },
  "routes": [
    "GET /health",
    "POST /api/billing/checkout",
    "POST /api/billing/portal",
    "POST /api/billing/webhook",
    "GET /api/license/status"
  ],
  "requiredSecrets": [
    "STRIPE_SECRET_KEY",
    "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"
  ],
  "storage": {
    "current": "NYRA_ENTITLEMENTS_FILE JSON store with atomic writes and health-check writable probe for dev/paid-beta rehearsal",
    "env": "NYRA_ENTITLEMENTS_FILE",
    "productionGuard": "NYRA_BILLING_REQUIRE_PERSISTENT_STORAGE=true or NODE_ENV=production requires NYRA_ENTITLEMENTS_FILE to be an absolute mounted persistent path",
    "healthCheck": "GET /health verifies entitlement storage is writable",
    "paidBetaRequirement": "absolute mounted persistent disk at minimum",
    "publicLaunchRequirement": "replace JSON file with managed database before broad public launch"
  },
  "stripeWebhook": {
    "path": "/api/billing/webhook",
    "requiredEvents": [
      "checkout.session.completed",
      "invoice.paid",
      "invoice.payment_failed",
      "customer.subscription.updated",
      "customer.subscription.deleted"
    ],
    "recommendedEvents": [
      "entitlements.active_entitlement_summary.updated"
    ]
  },
  "externalBlockers": [
    "monthly price",
    "hosted AI cap",
    "domain and HTTPS backend URL",
    "confirmed support inbox",
    "Stripe account identity/tax setup",
    "Stripe product and price",
    "Customer Portal configuration",
    "webhook endpoint secret",
    "persistent storage or managed database"
  ]
}