Payments (payments)
Payment driver dispatch + settlement events. The module owns the Payment
record and the four built-in payment adapters
(src/backend/adapters/built-in-adapters.ts), which it contributes to the
payment_methods module's paymentAdapterRegistry; per-vendor
adapters live in dedicated gateway modules.
Drivers
| Adapter key | Behaviour |
|---|---|
bank_transfer | Returns NextAction.kind='awaiting_transfer' with an ORDER-… reference; settlement happens out-of-band when the operator marks the order paid |
pickup | NextAction.kind='none' for cash-on-pickup |
credit_limit | NextAction.kind='none'; the reservation itself is made by orders (order-service.ts#placeOrder() calls credit_limits' CreditLimitService.reserve) inside the order-placement transaction |
gateway | Placeholder returning NextAction.kind='none'; a gateway module registers its own adapter that returns the redirect |
Public surface
Three admin routes, gated on this module's own permission codes:
| Verb + Path | Permission | Purpose |
|---|---|---|
GET /api/v1/admin/orders/:id/payments | payments:read | Full payment history for one order, including each attempt's provider payload |
POST /api/v1/admin/orders/:id/payments/retry | payments:write | Opens the next Payment attempt on an order |
POST /api/v1/payments/receive | payments:write | The receive_payment settlement ingress: declares a payment succeeded or failed |
The pair is deliberate. Reading an order's payment history is support and
finance work; opening a retry and declaring a settlement are money operations,
and an operator organisation separates the two. There is no third code for the
settlement ingress even though it is the most dangerous of the three, because
that route is transitional pending a signed PSP-webhook auth path — see the
reasoning in manifest.ts.
Until payments declared these, all three routes were gated on catalog:read
and catalog:write, so an operator who could edit a product could read every
payment's provider payload and mark an arbitrary payment settled. Upgrading:
a role that was reading payment data through catalog:read must be granted
payments:read explicitly on /admin-roles — there is no migration, because
one granting payments:read to every holder of catalog:read would reproduce
exactly the over-grant this change removes.
The ingress body bounds its providerDetails to a flat map of scalars
(operatorProviderDetailsSchema): the column is persisted verbatim and served
back in full, so what an operator may write into it is bounded by our schema
rather than by the caller's payload. Gateway integrations build the payload in
code and are not subject to that bound.
Beyond the routes, orders dispatch to the adapters via
order-service.ts#placeOrder(), and admin payment-status mutations go through
/api/v1/admin/orders/:id/payment-status, which orders owns.
The buyer's own retry (POST /api/v1/orders/:orderId/payments/retry) is a
customer route and authorises through requireCustomer, not a permission.
Refusals
A retry or a settlement the payment's own state refuses has its own code and a
sentence in English and Polish, read in the operator's language (the buyer's,
on the buyer's retry). Until issue #630 these were 409 VALIDATION_FAILED; the
status is unchanged.
| Code | Status | When | details |
|---|---|---|---|
PAYMENT_ALREADY_PAID | 409 | a retry of a paid order (code retry), or POST /api/v1/payments/receive with outcome: "failure" for a paid payment (code mark_failed; nothing is downgraded) | orderId, paymentId, status |
PAYMENT_REFUNDED | 409 | a retry of a refunded or partially refunded payment | orderId, paymentId, status |
PAYMENT_SETTLED_OUT_OF_BAND | 409 | a retry of an order settled out of band (deferred) | orderId, paymentId |
The buyer's retry answers PAYMENT_NOT_DUE, PAYMENT_ORDER_CLOSED or
PAYMENT_ADAPTER_UNAVAILABLE from its own gates first; it reaches the three
above only when the latest attempt changed after those gates read the order.
Gateway refunds
A gateway reports each refund — made from its dashboard or by a return
settlement — through its webhook, with the cumulative refunded amount, and the
payment records it. An amount with more than two decimal places is refused,
not rounded: the payment's refunded amount and status stay as they were, the
refusal is logged with the payment, the order, the reported amount and the
gateway's refund reference, and the payment is marked for manual attention
(providerDetails.refundAnomaly in the payment history). The webhook is still
acknowledged, so the gateway does not deliver it again; an operator checks the
refund with the gateway and settles it by hand.
Events emitted
payment.received.v1, payment.failed.v1, payment.refunded.v1. These are
events on the in-process event bus; none of them is delivered to outbound
webhooks.
Extension points
- New gateway — ship a module that implements
PaymentAdapterand contributes it topaymentAdapterRegistryfrom its boot hook, as described on thepayment_methodsmodule's page (Build your own payment-method module). - Fraud / 3DS hooks — slot in front of the adapter's start call before the order-placement transaction commits.