Skip to main content

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 keyBehaviour
bank_transferReturns NextAction.kind='awaiting_transfer' with an ORDER-… reference; settlement happens out-of-band when the operator marks the order paid
pickupNextAction.kind='none' for cash-on-pickup
credit_limitNextAction.kind='none'; the reservation itself is made by orders (order-service.ts#placeOrder() calls credit_limits' CreditLimitService.reserve) inside the order-placement transaction
gatewayPlaceholder 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 + PathPermissionPurpose
GET /api/v1/admin/orders/:id/paymentspayments:readFull payment history for one order, including each attempt's provider payload
POST /api/v1/admin/orders/:id/payments/retrypayments:writeOpens the next Payment attempt on an order
POST /api/v1/payments/receivepayments:writeThe 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.

CodeStatusWhendetails
PAYMENT_ALREADY_PAID409a 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_REFUNDED409a retry of a refunded or partially refunded paymentorderId, paymentId, status
PAYMENT_SETTLED_OUT_OF_BAND409a 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 PaymentAdapter and contributes it to paymentAdapterRegistry from its boot hook, as described on the payment_methods module'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.