nroxy/docs/ops/payment-system.md

# 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`