Skip to content

feat(billing): add opt-in Stripe top-ups credited only from verified webhooks - #75

Merged
ALikesToCode merged 3 commits into
feat/credits-ledgerfrom
feat/payment-billing
Oct 9, 2026
Merged

ALikesToCode merged 3 commits into
feat/credits-ledgerfrom
feat/payment-billing

Conversation

@ALikesToCode

Copy link
Copy Markdown
Owner

Summary

Adds opt-in Stripe top-ups. Credits are added only from a verified Stripe webhook, never from the browser's return page. With PAYMENTS_ENABLED unset or off (the default), /v1/payments/* returns 404 without touching payment storage, and nothing else changes.

  • Settings:
    • PAYMENTS_ENABLED. Empty means off; a malformed value is off with one warning.
    • PAYMENT_PROCESSOR_CONFIG_JSON holds {"processor": "stripe", "secret_key_ref", "return_origins", "product_name"}.
    • PAYMENT_WEBHOOK_KEY_REF names the webhook signing secret.
    • Configuration holds secret references only, and errors never include secrets.
  • Checkout: POST /v1/payments/checkout (gateway key) takes {amount_microusd, currency: "USD", idempotency_key, return_url}.
    • The amount must be whole cents, from /bin/bash.50 to ,000, and the return URL must use an allowlisted origin.
    • At most ten checkouts per principal per UTC day (429 payment_velocity_limited).
    • The same idempotency key replays the same checkout; a different body returns 409.
    • The gateway creates a Stripe Checkout Session with a fixed form body, an Idempotency-Key and only an opaque checkout ID in metadata, then checks the returned session's amount, currency and URL origin.
  • Webhook: POST /v1/payments/webhook takes no gateway key and is exempt from CSRF.
    • It verifies the raw body's Stripe-Signature: v1 values only, HMAC-SHA256 compared in constant time, timestamp within ±300 s.
    • It claims the event ID before any credit callback, so a replayed event returns 200 without crediting again.
    • It checks livemode, merchant, currency, amount and session against the stored checkout. A mismatch is recorded and not credited.
  • Mapped events:
    • checkout.session.completed with payment_status: paid, or checkout.session.async_payment_succeeded, credits once per checkout.
    • checkout.session.async_payment_failed marks the checkout failed.
    • charge.refunded and charge.dispute.created append compensation.
    • Other types are recorded and ignored.
  • Crediting: only through the injected PaymentCallback. When it is unavailable, the event stays pending_credit and the webhook returns 503 so Stripe retries.
  • No card data, names or emails are stored.

Details are in docs/payment-billing.md. Tests use fake HTTP only; nothing calls Stripe.

Wiring

All new files; no existing file changes. The existing Worker forwards the webhook to the Container byte for byte, without an edge key check, which a test confirms. The Wave 7 integration adds:

  • mounting register_payment_routes with the D1 store, the tenant context and the credits ledger's callback;
  • the private payments endpoint and its dispatcher entry.

Taxes, invoices and the processor account itself remain operator decisions.

Shared registrations

  • tests/test_payment_billing_worker.mjs in test:worker.
  • worker/payment-webhooks.mjs in the edge module inventory, and both payment routes in the Flask route inventory.
  • PAYMENTS_ENABLED, PAYMENT_PROCESSOR_CONFIG_JSON and PAYMENT_WEBHOOK_KEY_REF in the Container env keys.
  • payment_checkouts, payment_events, payment_velocity and payment_audit in REQUIRED_D1_TABLES.

Stacked on #74

Migration numbers must be contiguous in each PR, so this branch merges feat/credits-ledger (#74, migration 0037), which stacks on #73, #72, #71 and #70. Merge those first.

Tests

  • tests/test_payment_billing.py and tests/test_payment_billing_worker.mjs cover:
    • invalid signature, timestamp, merchant and currency;
    • a replayed event crediting once, and concurrent callbacks;
    • the redirect never crediting;
    • amount and velocity caps;
    • refunds appending compensation;
    • foreign workspaces;
    • a missing credit authority failing closed;
    • the default off state.
  • Full Python suite: 4,990 passed, 2 skipped. ruff, mypy and bandit are clean.
  • npm run test:worker: 1,850 passed. npm run test:integration: 7 passed.
  • cf:migrations:check reports 38 contiguous, additive migrations. test:deploy, free routes, client headers and the wrangler deploy --dry-run bundle all pass.
  • tests/test_frontend_build.mjs fails locally because @tailwindcss/cli is not installed. It fails the same way on main.

Apply the migration before enabling the flag: npx wrangler d1 migrations apply multillm-intelligence --remote.

CI notes

  • GitHub python/node jobs: the dependency-audit steps fail on every branch, including main. fix(deps): clear the CI dependency audit advisories #42 fixes that.
  • Workers Builds: fails on this stack because the Wave 3 base adds the AdmissionCoordinator Durable Object migration, which wrangler versions upload cannot apply. This is expected until wrangler deploy runs on main.

This is part of Wave 7. The README line comes with the Wave 7 integration PR.

…webhooks

PAYMENTS_ENABLED (off by default) adds POST /v1/payments/checkout, which
creates a Stripe Checkout Session for a whole-cent USD amount between $0.50
and $1,000 from an allowlisted return origin, with per-principal daily limits
and idempotent replay. POST /v1/payments/webhook verifies the raw body's v1
signature and timestamp, claims each event before any callback, and checks
livemode, merchant, currency, amount and session against the stored checkout.

Credits are added only through the injected payment callback, once per
checkout; refunds and disputes append compensation. The browser return page
never credits. Configuration holds secret references only (migration 0038).
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Oct 9, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 79eb3eda-32bb-43f4-b8a9-e490564e7712

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
multillm-proxy cc933b4 Oct 09 2026, 08:00 AM

@ALikesToCode
ALikesToCode merged commit 4dabea2 into feat/credits-ledger Oct 9, 2026
4 of 7 checks passed
@ALikesToCode
ALikesToCode deleted the feat/payment-billing branch October 26, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant