docs: describe current payment system
This commit is contained in:
sirily
170
docs/ops/payment-system.md
Normal file
170
docs/ops/payment-system.md
Normal file
@@ -0,0 +1,170 @@
|
|||||||
|
# Payment System
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
Describe how billing and payment processing currently work in `nproxy`.
|
||||||
|
|
||||||
|
This document is about the implemented system, not the desired future state.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
The current payment system covers:
|
||||||
|
- default subscription plan bootstrap
|
||||||
|
- user subscription creation at registration time
|
||||||
|
- invoice creation through a provider adapter
|
||||||
|
- manual admin activation when an invoice is confirmed as paid
|
||||||
|
- quota-cycle reset on successful activation
|
||||||
|
|
||||||
|
The current payment system does not yet cover:
|
||||||
|
- provider webhooks
|
||||||
|
- polling-based reconciliation
|
||||||
|
- automatic `expired` or `canceled` transitions
|
||||||
|
- recurring billing
|
||||||
|
|
||||||
|
## Main records
|
||||||
|
|
||||||
|
### `SubscriptionPlan`
|
||||||
|
- one default active plan is bootstrapped by `packages/db/src/bootstrap.ts`
|
||||||
|
- current default seed:
|
||||||
|
- `code`: `monthly`
|
||||||
|
- `displayName`: `Monthly`
|
||||||
|
- `monthlyRequestLimit`: `100`
|
||||||
|
- `monthlyPriceUsd`: `9.99`
|
||||||
|
- `billingCurrency`: `USDT`
|
||||||
|
|
||||||
|
### `Subscription`
|
||||||
|
- created for a new user during registration if the default plan exists
|
||||||
|
- starts in `pending_activation`
|
||||||
|
- becomes `active` only after successful invoice activation
|
||||||
|
- stores:
|
||||||
|
- `activatedAt`
|
||||||
|
- `currentPeriodStart`
|
||||||
|
- `currentPeriodEnd`
|
||||||
|
- `renewsManually`
|
||||||
|
|
||||||
|
### `PaymentInvoice`
|
||||||
|
- stores one provider-facing payment attempt for a subscription
|
||||||
|
- important fields:
|
||||||
|
- local `id`
|
||||||
|
- `subscriptionId`
|
||||||
|
- `provider`
|
||||||
|
- `providerInvoiceId`
|
||||||
|
- `status`
|
||||||
|
- `currency`
|
||||||
|
- `amountCrypto`
|
||||||
|
- `amountUsd`
|
||||||
|
- `paymentAddress`
|
||||||
|
- `expiresAt`
|
||||||
|
- `paidAt`
|
||||||
|
|
||||||
|
### `UsageLedgerEntry`
|
||||||
|
- records quota-affecting events
|
||||||
|
- on successful payment activation the system writes `cycle_reset`
|
||||||
|
- successful generations later write `generation_success`
|
||||||
|
|
||||||
|
### `AdminAuditLog`
|
||||||
|
- records state-changing admin actions
|
||||||
|
- the current admin `mark-paid` flow writes:
|
||||||
|
- `invoice_mark_paid`
|
||||||
|
- `invoice_mark_paid_replayed`
|
||||||
|
|
||||||
|
## Provider boundary
|
||||||
|
Payment-provider code stays behind `packages/providers/src/payments.ts`.
|
||||||
|
|
||||||
|
Current provider contract:
|
||||||
|
- `createInvoice(input) -> providerInvoiceId, paymentAddress, amountCrypto, amountUsd, currency, expiresAt`
|
||||||
|
|
||||||
|
Current runtime note:
|
||||||
|
- the provider adapter is still a placeholder adapter
|
||||||
|
- provider callbacks and status lookups are not implemented yet
|
||||||
|
- the rest of the payment flow is intentionally provider-agnostic
|
||||||
|
|
||||||
|
## Registration flow
|
||||||
|
1. User registers through `POST /api/auth/register`.
|
||||||
|
2. `packages/db/src/auth-store.ts` creates the user and session.
|
||||||
|
3. If the default plan exists, the store also creates a `Subscription` in `pending_activation`.
|
||||||
|
4. At this point the user has an account and a plan assignment, but not an active paid cycle.
|
||||||
|
|
||||||
|
## Invoice creation flow
|
||||||
|
1. Authenticated user calls `POST /api/billing/invoices`.
|
||||||
|
2. `packages/db/src/billing-store.ts` loads the latest subscription for that user.
|
||||||
|
3. If there is already a non-expired `pending` invoice for the same subscription, it is reused.
|
||||||
|
4. Otherwise the app calls the payment-provider adapter `createInvoice`.
|
||||||
|
5. The returned provider invoice data is persisted as a new local `PaymentInvoice` in `pending`.
|
||||||
|
6. The API returns invoice details, including provider invoice id, amount, address, and expiry time.
|
||||||
|
|
||||||
|
## Invoice listing flow
|
||||||
|
- `GET /api/billing/invoices` returns the user's invoices ordered by newest first.
|
||||||
|
- This is a read-only view over persisted `PaymentInvoice` rows.
|
||||||
|
|
||||||
|
## Current activation flow
|
||||||
|
The implemented activation path is manual and admin-driven.
|
||||||
|
|
||||||
|
1. An authenticated admin calls `POST /api/admin/invoices/:id/mark-paid`.
|
||||||
|
2. The web app resolves the admin session and passes actor metadata into the billing store.
|
||||||
|
3. `markInvoicePaid` runs inside one database transaction.
|
||||||
|
4. If the invoice is `pending`, the store:
|
||||||
|
- updates the invoice to `paid`
|
||||||
|
- sets `paidAt`
|
||||||
|
- updates the related subscription to `active`
|
||||||
|
- sets `activatedAt` if it was not already set
|
||||||
|
- sets `currentPeriodStart = paidAt`
|
||||||
|
- sets `currentPeriodEnd = paidAt + 30 days`
|
||||||
|
- clears `canceledAt`
|
||||||
|
- writes a `UsageLedgerEntry` with `entryType = cycle_reset`
|
||||||
|
- writes an `AdminAuditLog` entry `invoice_mark_paid`
|
||||||
|
5. The API returns the updated invoice.
|
||||||
|
|
||||||
|
## Idempotency and transition rules
|
||||||
|
`markInvoicePaid` is replay-safe.
|
||||||
|
|
||||||
|
### Allowed cases
|
||||||
|
- `pending -> paid`
|
||||||
|
- `paid -> paid` as a no-op replay
|
||||||
|
|
||||||
|
### Replay behavior
|
||||||
|
If the invoice is already `paid`:
|
||||||
|
- the subscription is not mutated again
|
||||||
|
- no extra `cycle_reset` entry is created
|
||||||
|
- an audit event `invoice_mark_paid_replayed` is written
|
||||||
|
|
||||||
|
### Rejected cases
|
||||||
|
If the invoice is already terminal:
|
||||||
|
- `expired`
|
||||||
|
- `canceled`
|
||||||
|
|
||||||
|
the store rejects the request with `invoice_transition_not_allowed`.
|
||||||
|
|
||||||
|
If the invoice does not exist, the store returns `invoice_not_found`.
|
||||||
|
|
||||||
|
## How quota ties to payment
|
||||||
|
- A user can create generation requests only with an active subscription.
|
||||||
|
- Approximate quota shown to the user is derived from `generation_success` entries since the current billing cycle start.
|
||||||
|
- A successful payment activation starts a new cycle by writing `cycle_reset` and moving the subscription window forward.
|
||||||
|
- Failed generations do not consume quota.
|
||||||
|
|
||||||
|
## HTTP surface
|
||||||
|
- `POST /api/billing/invoices`
|
||||||
|
- create or reuse the current pending invoice for the authenticated user
|
||||||
|
- `GET /api/billing/invoices`
|
||||||
|
- list the authenticated user's invoices
|
||||||
|
- `POST /api/admin/invoices/:id/mark-paid`
|
||||||
|
- admin-only manual payment activation path
|
||||||
|
|
||||||
|
## Error behavior
|
||||||
|
Current payment-specific errors surfaced by the web app:
|
||||||
|
- `invoice_not_found` -> `404`
|
||||||
|
- `invoice_transition_not_allowed` -> `409`
|
||||||
|
|
||||||
|
## Current limitations
|
||||||
|
- The system still depends on manual admin confirmation to activate access.
|
||||||
|
- No provider callback or reconciliation job updates invoice state automatically.
|
||||||
|
- No runtime path currently moves invoices to `expired` or `canceled`.
|
||||||
|
- The provider adapter does not yet verify external status or signatures.
|
||||||
|
- Subscription lifecycle beyond the current `mark-paid` path is still incomplete.
|
||||||
|
|
||||||
|
## Code references
|
||||||
|
- `packages/db/src/bootstrap.ts`
|
||||||
|
- `packages/db/src/auth-store.ts`
|
||||||
|
- `packages/db/src/billing-store.ts`
|
||||||
|
- `packages/db/src/account-store.ts`
|
||||||
|
- `packages/providers/src/payments.ts`
|
||||||
|
- `apps/web/src/main.ts`
|
||||||
Reference in New Issue
Block a user