# `@wrnexus/payment` — proposal

**Status:** draft for review
**Date:** 2026-08-23

One package that gives an application real payments: gateway configuration, initialisation,
capture, refunds, stored methods, an admin surface, and UI components — so a team never writes
this again.

## The one rule that shapes everything

**The package never touches a raw card number.**

Every supported gateway offers hosted fields or a hosted checkout that tokenises the card in
the customer's browser, against the gateway's domain, before anything reaches your server. That
is what keeps an application in PCI **SAQ-A** — roughly a self-assessment questionnaire —
instead of SAQ-D, which is an audit programme with a six-figure floor.

So the package's UI components mount the gateway's own fields. `PayNow` renders a button that
opens a gateway session; it never renders an `<input name="cardNumber">`, and the package
exposes no API that would accept one. A framework that makes the cheap wrong thing easy will
have it done by someone in a hurry.

## The second rule: the webhook is the truth

A browser redirect saying "payment succeeded" is a claim from an untrusted client. The
authoritative event is the gateway's signed webhook.

So `checkPayment()` reads local state that webhooks maintain, and the local record is only ever
advanced by a verified webhook or a server-side gateway query — never by a client callback. The
redirect is a UX affordance: it tells the customer where to look, not the system what happened.

This is the single most common way a payment integration leaks money, and it is a design
decision, not a runtime check.

## Money model — the same discipline as metering

Payments are **append-only**, exactly like `@wrnexus/metering`'s ledger, and for the same
reason: a balance you cannot explain is a balance nobody trusts.

| Table                  | Holds                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `wrn_payment_intent`   | one row per attempt: amount, currency, gateway, status, idempotency key             |
| `wrn_payment_event`    | append-only; every webhook and state transition, with the raw signed payload        |
| `wrn_payment_refund`   | one row per refund attempt, linked to its intent                                    |
| `wrn_payment_method`   | stored gateway tokens — never card data, never a PAN, at most a brand and last four |
| `wrn_payment_customer` | the mapping from your user id to each gateway's customer id                         |

A payment's current status is derived from its events, not from a mutable column that a race can
clobber. The `status` column on the intent is a cache of that derivation, and the package ships
a reconciliation command that recomputes it and reports disagreements.

**Idempotency is mandatory, not optional.** Every initialise and every refund carries a key; a
repeat with the same key returns the original result rather than charging twice. This is where a
double-click becomes a double-charge, and it should be impossible to opt out of.

## Gateways are adapters

```ts
export interface PaymentGateway<TConfig = unknown> {
  readonly id: string; // "stripe" | "razorpay" | "paypal" | ...
  readonly capabilities: GatewayCapabilities;
  readonly supports: { currencies: string[] | "any"; countries: string[] | "any" };

  createIntent(input: CreateIntentInput): Promise<GatewayIntent>;
  fetchIntent(intentRef: string): Promise<GatewayIntent>;
  cancelIntent(intentRef: string, reason: string): Promise<GatewayIntent>;
  refund(input: RefundInput): Promise<GatewayRefund>;
  verifyWebhook(req: Request, secret: string): Promise<WebhookEvent>; // signature check

  capture?(intentRef: string, amount?: Money): Promise<GatewayIntent>; // authorize-then-capture
  listMethods?(customerRef: string): Promise<GatewayMethod[]>;
  attachMethod?(customerRef: string, token: string): Promise<GatewayMethod>;
  detachMethod?(methodRef: string): Promise<void>;
  createCustomer?(input: CustomerInput): Promise<string>;

  readonly clientConfig: (intent: GatewayIntent) => Record<string, string>; // safe to send
}
```

`clientConfig` exists so the boundary is explicit: it returns exactly what the browser may see —
a publishable key and a session id, never a secret. Anything not returned by it cannot reach the
client, which is a structural guarantee rather than a code-review habit.

### Capabilities are declared, and the difference is refused loudly

This is the part that decides whether a multi-gateway abstraction holds. **Gateways are not
interchangeable.** Some have no authorise-then-capture. Some cannot do partial refunds. Some
have no stored-method vault. Some only settle in one currency.

An interface that pretends otherwise produces the worst failure mode there is: an application
calls `capturePayment()` against a gateway that has no such concept, and gets a confusing
gateway error at the moment money should have moved.

So every adapter declares what it can do, and the package refuses the rest **at call time with a
named reason** — and, better, at **build time** where the gateway is statically known:

```ts
export interface GatewayCapabilities {
  authorizeThenCapture: boolean; // Stripe yes, Razorpay effectively no
  partialRefund: boolean;
  multipleRefunds: boolean;
  storedMethods: boolean;
  customerVault: boolean;
  hostedFields: boolean; // inline hosted inputs
  hostedCheckout: boolean; // full redirect/modal
  webhookSignature: boolean; // an adapter without this is refused in production
  payouts: boolean;
  disputes: boolean;
}
```

`capabilitiesOf("razorpay").partialRefund` is a real answer an application can branch on, and
`RefundButton` reads it to decide whether to offer an amount field or only a full refund. A
capability an adapter does not declare is not merely unimplemented — it is refused, with a
message naming the gateway and the capability.

**`webhookSignature: false` is refused outright in production.** An adapter that cannot verify a
webhook cannot be trusted to tell you money moved, and the whole design rests on that.

### The roster

**Tier 1 — ship first, fully covered by the contract suite:**

| Adapter    | Notes                                                                              |
| ---------- | ---------------------------------------------------------------------------------- |
| `sandbox`  | behaves like a real gateway, signed webhooks, injectable failure modes, no network |
| `stripe`   | global; hosted fields, auth-then-capture, vault, partial and multiple refunds      |
| `razorpay` | India-first; hosted checkout, INR-centric, no true auth-then-capture               |
| `paypal`   | global; hosted checkout, its own order/capture model                               |

Two real gateways prove the abstraction; one does not. Stripe and Razorpay are deliberately the
first pair because they **differ** — capture model, currency spread, refund semantics — so the
capability system is exercised rather than assumed.

**Tier 2 — same contract, added after the abstraction has survived Tier 1:**
`adyen`, `square`, `braintree`, `mollie`, `checkout.com`, `paddle` (merchant-of-record, so tax
and invoicing differ meaningfully).

**Tier 3 — regional, community-shaped:**
`payu`, `cashfree`, `phonepe`, `paytm` (India); `paystack`, `flutterwave` (Africa);
`midtrans`, `xendit` (South-East Asia); `authorize.net` (US legacy); `mercadopago` (LatAm).

### Any developer can add one

The roster is a starting set, not a ceiling. A custom adapter is a first-class citizen:

```ts
import { defineGateway } from "@wrnexus/payment";

export const acme = defineGateway({
  id: "acme",
  capabilities: { partialRefund: true, storedMethods: false, webhookSignature: true /* … */ },
  supports: { currencies: ["INR", "USD"], countries: ["IN"] },
  async createIntent(input) {
    /* … */
  },
  async verifyWebhook(req, secret) {
    /* … */
  },
  // …
});
```

`defineGateway` validates the shape at registration and runs the **shared contract suite** in
tests, so a third-party adapter is held to exactly the standard the built-in ones are. An adapter
that passes the suite behaves identically to Stripe's from the application's point of view; one
that does not, fails in CI rather than in production.

## Configuration

Config is **per-gateway and typed** — each adapter declares its own shape, so a missing
`webhookSecret` is a type error, not a 3am discovery:

```ts
// wrnexus.config.ts
payment: {
  default: "stripe",
  currency: "INR",

  gateways: {
    stripe: {
      secretKey:      env("STRIPE_SECRET_KEY"),
      publishableKey: env("STRIPE_PUBLISHABLE_KEY"),
      webhookSecret:  env("STRIPE_WEBHOOK_SECRET"),
      apiVersion:     "2026-03-31",
      captureMethod:  "automatic",        // or "manual" for auth-then-capture
    },
    razorpay: {
      keyId:         env("RAZORPAY_KEY_ID"),
      keySecret:     env("RAZORPAY_KEY_SECRET"),
      webhookSecret: env("RAZORPAY_WEBHOOK_SECRET"),
      theme:         { color: "#0e7c86" },
    },
    acme: { apiKey: env("ACME_KEY"), webhookSecret: env("ACME_WEBHOOK_SECRET") },
  },

  // Optional: pick a gateway per payment instead of always using the default.
  route(intent) {
    if (intent.currency === "INR") return "razorpay";
    if (intent.country === "US") return "stripe";
    return "stripe";
  },

  sandbox: process.env.NODE_ENV !== "production",
}
```

Selection has three levels, most specific winning: an explicit `gateway` on the call, then
`route()`, then `default`. A `route()` that returns a gateway which is not configured, or which
cannot settle the intent's currency, is a startup error where it can be detected statically and
a named refusal where it cannot.

**Registering a custom adapter is a config line, not a fork:**

```ts
import { acme } from "./payments/acme.ts";
payment: { adapters: [acme], default: "acme", /* … */ }
```

**Refuse to boot on a misconfiguration rather than failing at the first payment.** A live secret
key with `sandbox: true`, or a missing webhook secret, is a startup error naming the variable —
the same lesson as `APP_ENCRYPTION_KEY` failing as an opaque WebCrypto error until it was made
explicit.

## The helper surface

```ts
// Lifecycle
initializePayment(input): Promise<PaymentIntent>   // amount, currency, subject, metadata, idempotencyKey
confirmPayment(id): Promise<PaymentIntent>         // server-side confirm where the gateway needs it
capturePayment(id, amount?): Promise<PaymentIntent>// for auth-then-capture flows
cancelPayment(id, reason): Promise<PaymentIntent>
checkPayment(id): Promise<PaymentStatus>           // derived from events, never from a client claim
syncPayment(id): Promise<PaymentIntent>            // authoritative re-read from the gateway

// Refunds
refundPayment({ id, amount?, reason, idempotencyKey }): Promise<Refund>  // partial by default
listRefunds(id): Promise<Refund[]>
refundableAmount(id): Promise<Money>               // amount minus refunds already settled

// Stored methods
paymentMethods(userId): Promise<PaymentMethod[]>
attachPaymentMethod(userId, token): Promise<PaymentMethod>
detachPaymentMethod(methodId): Promise<void>
setDefaultPaymentMethod(userId, methodId): Promise<void>

// Records and reporting
getPayment(id) / listPayments(filter)              // filter by user, status, gateway, date range
paymentTotals(filter): Promise<{ captured, refunded, net, byCurrency }>
reconcilePayments(range): Promise<Discrepancy[]>   // local vs gateway, the operator's safety net

// Webhooks
paymentWebhookHandler(gatewayId): RouteHandler      // signature-verified, idempotent, replay-safe
```

Every function that moves money is **non-throwing and returns a result** with a `fault`
discriminator, matching `@wrnexus/metering`: a refusal's reason is safe to show a customer, a
fault's reason belongs only in the log. That distinction was learned the hard way — a naive
catch once answered "payment required" with a raw SQLite message.

### `refundableAmount` earns its place

Partial refunds are where integrations quietly go wrong: two concurrent partial refunds each
check "is there enough left?", both see yes, and together exceed the capture. `refundPayment`
must enforce the cap with a conditional write — the same shape as metering's reserve — not with
a read-then-write.

## Migrations ship with the package

`@wrnexus/authz` provisioning nothing is a real cost in this codebase: every application
hand-wires `ensureAuthzTables`, and the framework's own example copies DDL by hand and silently
drifts. Payment must not repeat that.

The package is a **plugin**. It contributes its migrations, its webhook route, and its authz
permissions (`payment:read`, `payment:refund`, `payment:configure`) on install. An application
adds a config block and gets a working, guarded, migrated payment system.

## UI components

Every component mounts gateway-hosted fields; none collects card data itself.

| Component           | Does                                                                             |
| ------------------- | -------------------------------------------------------------------------------- |
| `PayNow`            | the button: opens a gateway session, shows pending/success/failure, emits `paid` |
| `PaymentSheet`      | hosted fields inline, with the gateway's own validation surfaced                 |
| `PaymentMethodList` | stored methods, set-default, detach — brand and last four only                   |
| `PaymentStatus`     | live status for one intent, driven by `checkPayment`                             |
| `RefundButton`      | admin-side, requires a reason, shows `refundableAmount`                          |
| `PaymentHistory`    | a customer's payments and refunds                                                |
| `PaymentSummary`    | totals by status and currency for a range                                        |

`PayNow` needs to survive the customer closing the tab mid-payment, so its resolved state comes
from `checkPayment`, not from whether the callback fired.

**One caveat to state plainly:** these components will hit `GAP-01` today. A `PaymentStatus`
that first appears client-side renders as an empty placeholder, and a `PayNow` whose props change
after mount will not update. Until the client component runtime lands, these components must be
built server-rendered-first with real navigation, exactly as the Sendline admin console was.

## Admin surface

A payments console — list and filter, view one payment with its full event timeline, issue a
refund with a required reason, inspect webhook deliveries and replay a failed one, and run
reconciliation. Every privileged action writes an audit entry, so the package should either take
a dependency on an audit interface or define one.

## Verification — the standard this project now holds

Unit and integration tests are necessary and insufficient. The package is done when:

1. Every gateway adapter — built-in **and** third-party — passes one shared contract suite, so
   behaviour cannot drift per gateway. An adapter declaring a capability it does not honour fails
   the suite; an adapter honouring one it does not declare fails too, because a silent extra is
   how an application comes to depend on something the next gateway lacks.
2. The sandbox adapter can drive a full lifecycle offline: initialise, webhook, capture, partial
   refund, over-refund refused, reconciliation clean.
3. **A real payment is driven end to end in a browser against a gateway's test mode**, and the
   money is confirmed in the gateway's own dashboard — not in our database. Phase 3 proved that a
   row saying `sent` is not the same as an email arriving; a row saying `captured` is not the same
   as money moving.
4. A replayed webhook, a duplicated initialise, and a double-clicked refund each change the
   ledger exactly once.
5. Reconciliation over a deliberately corrupted local row reports the discrepancy rather than
   hiding it.

## What this package deliberately does not do

- **No card data, ever.** No PAN, no CVV, no expiry, in any API, table, log or component.
- **No invented gateway.** The sandbox adapter is clearly a sandbox and says so in its UI.
- **No subscription billing in v1.** Recurring is a genuinely separate problem — plans, proration,
  dunning, retries — and bolting it on would compromise both.
- **No currency conversion.** Store and settle in the currency charged; a converted number in a
  ledger is a number nobody can reconcile.
- **No silent capture of an expired authorisation.** It fails loudly.

## Build order

1. Core: schema, append-only events, status derivation, idempotency, non-throwing results
2. The capability system, `defineGateway`, and the shared adapter contract suite
3. The sandbox adapter — first consumer of the contract suite, and the thing every later
   adapter is checked against
4. **Stripe, then Razorpay.** Deliberately this pair, because they differ on capture model,
   currency spread and refund semantics. Building them together is what stops the abstraction
   quietly becoming "Stripe, with names changed"
5. Gateway selection: explicit, `route()`, default — with the misconfiguration errors
6. The webhook route: signature verification, replay safety, event storage
7. Refunds, including the concurrent partial-refund cap and the `partialRefund: false` path
8. Stored methods and customers, behind `storedMethods`
9. PayPal — the third gateway, and the real test of whether Tier 2 can be added by someone who
   did not design the abstraction
10. Admin console and reconciliation
11. UI components, capability-aware
12. Browser verification against a gateway test mode