@endora-commerce/mod-payments 0.100.0

package/dist/backend/services/payment-reference-port.js

@@ -0,0 +1,70 @@
+import { Payment } from '../entities/payment.entity.js';
+/**
+ * The one write the four payment gateways make into this module's table
+ * (feature 075, Phase P) — the write side of
+ * `PaymentReadPort.findByExternalReference`.
+ *
+ * Each gateway opens its own provider object for an attempt (a Stripe
+ * PaymentIntent or Checkout Session, a TPay transaction, a PayU order, an
+ * Autopay transaction) and then records that object's identifier on the
+ * attempt, so a later provider event carrying only the provider's reference
+ * resolves back to a payment. Four modules were doing it with
+ * `em.findOne(Payment, …)` and a field assignment, which is this module's row
+ * being written by somebody else's `EntityManager`.
+ *
+ * It is deliberately not on the Command Bus, and the four call sites all say
+ * why in their own words: this is provider-integration bookkeeping, not an
+ * operator decision. The state change an operator is answerable for is the
+ * settlement, and that is audited in the payments/orders flow.
+ */
+export class PaymentReferenceService {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    async stampExternalReference(paymentId, externalReference) {
+        // Records the provider's own identifier for an attempt so its later event
+        // resolves; provider-integration bookkeeping. The exemption sits on `stamp`,
+        // which is where the write is — a second marker here guarded nothing, and
+        // since D-89(c) the staleness half says so instead of counting it.
+        return this.stamp(paymentId, externalReference, false);
+    }
+    async stampExternalReferenceIfAbsent(paymentId, externalReference) {
+        // As above, for the gateway whose first reference is the one its provider
+        // metadata was written against; `stamp` carries the exemption.
+        return this.stamp(paymentId, externalReference, true);
+    }
+    async mergeProviderDetails(paymentId, patch) {
+        // command-coverage-ignore: records what the provider said about an attempt
+        // so a later provider event can act on it; provider-integration
+        // bookkeeping, exactly as the reference stamp above.
+        const em = this.emFactory();
+        const payment = await em.findOne(Payment, { id: paymentId });
+        if (!payment)
+            return false;
+        payment.providerDetails = { ...(payment.providerDetails ?? {}), ...patch };
+        await em.flush();
+        return true;
+    }
+    async stamp(paymentId, externalReference, onlyIfAbsent) {
+        // command-coverage-ignore: the mutation both public entry points delegate
+        // to, and the one place the exemption belongs — recording the provider's own
+        // identifier for an attempt is integration bookkeeping, not an operator
+        // decision. Marking only the callers left `--strict` blocking on the line
+        // below (feature 075, Phase P); marking the callers *as well* left two
+        // markers guarding nothing, which is what D-89(c) taught the staleness half
+        // to report.
+        const em = this.emFactory();
+        const payment = await em.findOne(Payment, { id: paymentId });
+        if (!payment)
+            return false;
+        if (onlyIfAbsent && payment.externalReference)
+            return false;
+        if (payment.externalReference === externalReference)
+            return false;
+        payment.externalReference = externalReference;
+        await em.flush();
+        return true;
+    }
+}
+//# sourceMappingURL=payment-reference-port.js.map

package/dist/backend/services/payment-reference-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-reference-port.js","sourceRoot":"","sources":["../../../src/backend/services/payment-reference-port.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,uBAAuB;IACL;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D,KAAK,CAAC,sBAAsB,CAAC,SAAiB,EAAE,iBAAyB;QACvE,0EAA0E;QAC1E,6EAA6E;QAC7E,0EAA0E;QAC1E,mEAAmE;QACnE,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,8BAA8B,CAClC,SAAiB,EACjB,iBAAyB;QAEzB,0EAA0E;QAC1E,+DAA+D;QAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,SAAiB,EACjB,KAA8B;QAE9B,2EAA2E;QAC3E,gEAAgE;QAChE,qDAAqD;QACrD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,OAAO,CAAC,eAAe,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QAC3E,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,KAAK,CACjB,SAAiB,EACjB,iBAAyB,EACzB,YAAqB;QAErB,0EAA0E;QAC1E,6EAA6E;QAC7E,wEAAwE;QACxE,0EAA0E;QAC1E,uEAAuE;QACvE,4EAA4E;QAC5E,aAAa;QACb,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,IAAI,YAAY,IAAI,OAAO,CAAC,iBAAiB;YAAE,OAAO,KAAK,CAAC;QAC5D,IAAI,OAAO,CAAC,iBAAiB,KAAK,iBAAiB;YAAE,OAAO,KAAK,CAAC;QAClE,OAAO,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC9C,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/backend/services/payment-refund.d.ts

@@ -0,0 +1,55 @@
+import type { OrderReadPort, PaymentMethodReadPort, PaymentRefundInput, PaymentRefundPort, PaymentRefundResult } from '@endora-commerce/contracts';
+/**
+ * Payments-side implementation of the returns module's `PaymentRefundPort`
+ * (feature 046, R5).
+ *
+ * Gateway payments (`kind === 'gateway'`) are delegated to the PSP handler
+ * registered under the **order's** payment adapter (snapshot / order method).
+ * The settlement form's `refundPaymentMethodId` is ledger metadata only — it
+ * must not pick which PSP to call (otherwise Autopay orders refunded under a
+ * bank-transfer method never hit Autopay).
+ *
+ * Offline methods (bank transfer, credit limit, pickup) are recorded as
+ * `issued` — the operator performs the actual transfer.
+ *
+ * **A gateway the operator switched off is refused, not recorded (D-71).**
+ * `gatewayRefundRegistry` skips an absent owner's handler, and this provider
+ * used to answer the resulting gap with `pending_manual`. Every layer above
+ * reads that as *settled*: `ReturnSettlementService` goes on to resolve the
+ * case, write the `Refund` row, issue the corrective invoice and mail the
+ * customer, and the admin's settlement card branches on `'failed'` only, so the
+ * operator is told "Settled." while no money has moved and the PSP was never
+ * called. Nothing in the execution path was missing a presence probe — the
+ * probe was right and the *outcome* was wrong.
+ *
+ * So the refusal is a {@link ModuleDisabledError}: the same 503 envelope, with
+ * the same `Retry-After`, that any other call into a switched-off module
+ * produces. It leaves the case exactly where it was, which is the truthful
+ * state, and it names the module — switching it back on is the whole remedy.
+ *
+ * `pending_manual` stays, and keeping the two apart is the point: a deployment
+ * that never installed a PSP integration is not in a temporary state and has
+ * nothing to switch on, so its refunds belong on the platform's books for a
+ * person to settle.
+ */
+export declare class PaymentRefundProvider implements PaymentRefundPort {
+    private readonly orderRead;
+    private readonly paymentMethodRead;
+    /**
+     * Feature 075 Phase C — both reads are somebody else's, both are reads, and
+     * neither is inside a transaction this class opens: the order comes from
+     * `orderReadPort` and the payment method from `paymentMethodReadPort`. They
+     * fail closed, which is the same answer D-71 already reaches for a
+     * switched-off gateway and for the same reason — resolving a refund against
+     * data the platform will not read is worse than refusing it.
+     */
+    constructor(orderRead: OrderReadPort, paymentMethodRead: PaymentMethodReadPort);
+    refund(input: PaymentRefundInput): Promise<PaymentRefundResult>;
+    /**
+     * Prefer the adapter the order was placed with (snapshot), then the order's
+     * payment method row. Do not use the settlement refund-method id for PSP
+     * resolution when the order snapshot already names an adapter.
+     */
+    private resolveOrderAdapterKey;
+}
+//# sourceMappingURL=payment-refund.d.ts.map

package/dist/backend/services/payment-refund.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-refund.d.ts","sourceRoot":"","sources":["../../../src/backend/services/payment-refund.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAEb,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAU3D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAVpC;;;;;;;OAOG;gBAEgB,SAAS,EAAE,aAAa,EACxB,iBAAiB,EAAE,qBAAqB;IAGrD,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA4BrE;;;;OAIG;YACW,sBAAsB;CAmBrC"}

package/dist/backend/services/payment-refund.js

@@ -0,0 +1,101 @@
+import { ModuleDisabledError } from '@endora-commerce/platform/kernel';
+import { gatewayRefundRegistry } from './registry-singleton.js';
+/**
+ * Payments-side implementation of the returns module's `PaymentRefundPort`
+ * (feature 046, R5).
+ *
+ * Gateway payments (`kind === 'gateway'`) are delegated to the PSP handler
+ * registered under the **order's** payment adapter (snapshot / order method).
+ * The settlement form's `refundPaymentMethodId` is ledger metadata only — it
+ * must not pick which PSP to call (otherwise Autopay orders refunded under a
+ * bank-transfer method never hit Autopay).
+ *
+ * Offline methods (bank transfer, credit limit, pickup) are recorded as
+ * `issued` — the operator performs the actual transfer.
+ *
+ * **A gateway the operator switched off is refused, not recorded (D-71).**
+ * `gatewayRefundRegistry` skips an absent owner's handler, and this provider
+ * used to answer the resulting gap with `pending_manual`. Every layer above
+ * reads that as *settled*: `ReturnSettlementService` goes on to resolve the
+ * case, write the `Refund` row, issue the corrective invoice and mail the
+ * customer, and the admin's settlement card branches on `'failed'` only, so the
+ * operator is told "Settled." while no money has moved and the PSP was never
+ * called. Nothing in the execution path was missing a presence probe — the
+ * probe was right and the *outcome* was wrong.
+ *
+ * So the refusal is a {@link ModuleDisabledError}: the same 503 envelope, with
+ * the same `Retry-After`, that any other call into a switched-off module
+ * produces. It leaves the case exactly where it was, which is the truthful
+ * state, and it names the module — switching it back on is the whole remedy.
+ *
+ * `pending_manual` stays, and keeping the two apart is the point: a deployment
+ * that never installed a PSP integration is not in a temporary state and has
+ * nothing to switch on, so its refunds belong on the platform's books for a
+ * person to settle.
+ */
+export class PaymentRefundProvider {
+    orderRead;
+    paymentMethodRead;
+    /**
+     * Feature 075 Phase C — both reads are somebody else's, both are reads, and
+     * neither is inside a transaction this class opens: the order comes from
+     * `orderReadPort` and the payment method from `paymentMethodReadPort`. They
+     * fail closed, which is the same answer D-71 already reaches for a
+     * switched-off gateway and for the same reason — resolving a refund against
+     * data the platform will not read is worse than refusing it.
+     */
+    constructor(orderRead, paymentMethodRead) {
+        this.orderRead = orderRead;
+        this.paymentMethodRead = paymentMethodRead;
+    }
+    async refund(input) {
+        const order = await this.orderRead.findById(input.orderId);
+        const kind = order?.paymentMethodSnapshot?.kind;
+        if (kind === 'gateway') {
+            const adapterKey = await this.resolveOrderAdapterKey(order, input.paymentMethodId);
+            const handler = gatewayRefundRegistry.resolve(adapterKey);
+            if (handler) {
+                return handler.refund(input);
+            }
+            // Two different situations behind one empty `resolve`, and only one of
+            // them is an outcome. A gateway whose module is switched off is a
+            // capability that is supposed to be here: refuse, so nothing downstream
+            // resolves the case, issues a correction or mails the customer over a
+            // refund that did not happen (D-71). `absentOwnerFor` is presence-blind
+            // for exactly this — it still names the contributor.
+            const absentOwner = gatewayRefundRegistry.absentOwnerFor(adapterKey);
+            if (absentOwner !== null)
+                throw new ModuleDisabledError(absentOwner);
+            // Nobody ever registered a handler for this adapter: there is no module
+            // to switch on, so the refund goes on the platform's books, named, for a
+            // person to settle.
+            return {
+                state: 'pending_manual',
+                failureReason: 'Gateway refunds require a PSP refund integration.',
+            };
+        }
+        return { state: 'issued', externalReference: input.idempotencyKey };
+    }
+    /**
+     * Prefer the adapter the order was placed with (snapshot), then the order's
+     * payment method row. Do not use the settlement refund-method id for PSP
+     * resolution when the order snapshot already names an adapter.
+     */
+    async resolveOrderAdapterKey(order, settlementPaymentMethodId) {
+        const fromSnapshot = order?.paymentMethodSnapshot?.adapter?.trim();
+        if (fromSnapshot)
+            return fromSnapshot;
+        if (order?.paymentMethodId) {
+            const method = await this.paymentMethodRead.findById(order.paymentMethodId);
+            if (method?.adapter)
+                return method.adapter;
+        }
+        // Last resort: settlement form method (legacy callers / missing snapshot).
+        if (settlementPaymentMethodId) {
+            const method = await this.paymentMethodRead.findById(settlementPaymentMethodId);
+            return method?.adapter ?? null;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=payment-refund.js.map

package/dist/backend/services/payment-refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-refund.js","sourceRoot":"","sources":["../../../src/backend/services/payment-refund.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,qBAAqB;IAUb;IACA;IAVnB;;;;;;;OAOG;IACH,YACmB,SAAwB,EACxB,iBAAwC;QADxC,cAAS,GAAT,SAAS,CAAe;QACxB,sBAAiB,GAAjB,iBAAiB,CAAuB;IACxD,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAC,KAAyB;QACpC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,KAAK,EAAE,qBAAqB,EAAE,IAAI,CAAC;QAChD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;YACnF,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC1D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,uEAAuE;YACvE,kEAAkE;YAClE,wEAAwE;YACxE,sEAAsE;YACtE,wEAAwE;YACxE,qDAAqD;YACrD,MAAM,WAAW,GAAG,qBAAqB,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;YACrE,IAAI,WAAW,KAAK,IAAI;gBAAE,MAAM,IAAI,mBAAmB,CAAC,WAAW,CAAC,CAAC;YACrE,wEAAwE;YACxE,yEAAyE;YACzE,oBAAoB;YACpB,OAAO;gBACL,KAAK,EAAE,gBAAgB;gBACvB,aAAa,EAAE,mDAAmD;aACnE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;IACtE,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,sBAAsB,CAClC,KAAyB,EACzB,yBAA6C;QAE7C,MAAM,YAAY,GAAG,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnE,IAAI,YAAY;YAAE,OAAO,YAAY,CAAC;QAEtC,IAAI,KAAK,EAAE,eAAe,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;YAC5E,IAAI,MAAM,EAAE,OAAO;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC;QAC7C,CAAC;QAED,2EAA2E;QAC3E,IAAI,yBAAyB,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;YAChF,OAAO,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC;QACjC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/backend/services/payment-retry-service.d.ts

@@ -0,0 +1,45 @@
+import { type CustomerAccountReadPort, type OrderReadPort, type OrderTransitionPort, type PaymentAdapterRegistryPort, type PaymentRetryResult } from '@endora-commerce/contracts';
+import type { PaymentService } from './payment-service.js';
+export interface PaymentRetryDeps {
+    orderRead: OrderReadPort;
+    customerAccountRead: CustomerAccountReadPort;
+    paymentService: PaymentService;
+    /**
+     * The lifecycle read, for the terminality term. `orders` owns the graph and
+     * the graph is what decides which statuses are ends — this module may not
+     * name one.
+     */
+    orderTransition: OrderTransitionPort;
+    /**
+     * Read per call rather than captured: the registry is contributed at boot by
+     * whichever gateway modules are present, and an operator can switch one off
+     * between two requests.
+     */
+    paymentAdapterRegistry: () => PaymentAdapterRegistryPort;
+    assertOrganizationCanTransact: (organizationId: string) => Promise<void>;
+}
+export declare class PaymentRetryService {
+    private readonly deps;
+    constructor(deps: PaymentRetryDeps);
+    /**
+     * Open (or resume) the buyer's own next payment attempt for `orderId`.
+     *
+     * @throws 404 when the order does not exist or carries no payment attempt.
+     * @throws 403 when the caller did not place the order.
+     * @throws 409 `PAYMENT_NOT_DUE` when the money is not the buyer's to pay —
+     *         the order is paid, drawn against a credit limit, or refunded.
+     * @throws 409 `PAYMENT_ORDER_CLOSED` when the order's lifecycle status is
+     *         terminal. A different condition and so a different code: the money
+     *         may well still be owed, but the order it was owed on is over.
+     * @throws 409 `PAYMENT_ADAPTER_UNAVAILABLE` when the method the order was
+     *         placed with has no adapter registered any more. A third condition,
+     *         and the only one that is about the shop rather than the order.
+     * @throws whatever `assertOrganizationCanTransact` throws for a suspended or
+     *         blocked organisation — the route maps it, exactly as placement does.
+     */
+    retryForCustomer(input: {
+        orderId: string;
+        customerAccountId: string;
+    }): Promise<PaymentRetryResult>;
+}
+//# sourceMappingURL=payment-retry-service.d.ts.map

package/dist/backend/services/payment-retry-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-retry-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/payment-retry-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAE5B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAE/B,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA6D3D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,aAAa,CAAC;IACzB,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,cAAc,EAAE,cAAc,CAAC;IAC/B;;;;OAIG;IACH,eAAe,EAAE,mBAAmB,CAAC;IACrC;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;IACzD,6BAA6B,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,gBAAgB;IAEnD;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA6HhC"}

package/dist/backend/services/payment-retry-service.js

@@ -0,0 +1,187 @@
+import { ERROR_CODES, } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { paymentsErrorCodes } from '../../manifest.js';
+/**
+ * A buyer paying an order of theirs again after the first attempt did not go
+ * through (issue #264).
+ *
+ * Before this existed there was no supported path at all. `/checkout/pay?id=…`
+ * is linked from the checkout submit action and from nowhere else, so a buyer
+ * whose card was declined had the page in their history or nothing; and going
+ * back through `/checkout` would have placed a **second** order for goods the
+ * first one still has allocated. The four redirect-mode gateways had not even
+ * that: the gateway URL is returned once, in the place-order response's
+ * `nextAction`, which is a virtual column and is never persisted.
+ *
+ * ### What this decides on, and what it deliberately does not
+ *
+ * The refusals below take **two** terms: the payment axis — is this order paid,
+ * is there an attempt, has it failed — and, since feature 085's Phase D,
+ * whether the order's lifecycle status is terminal.
+ *
+ * Reading the lifecycle at all used to be unsafe: every payment method in the
+ * tree was seeded
+ * `status_on_failure = 'cancelled'`, so the settlement ingress made an order
+ * terminal on the first decline and reading `order.status` would have refused
+ * exactly the buyers this exists for. Feature 085 answered the product question
+ * behind it — a declined payment now holds the order at the method's failure
+ * status, seeded `on_hold`, and records the decline on the money axis as
+ * `paymentStatus = 'failed'`. So a declined order is no longer terminal, and
+ * the cost this doc block used to state — that a hand-cancelled order was
+ * indistinguishable from an ingress-cancelled one — is retired with it: the
+ * ingress cancels nothing.
+ *
+ * The money term is an **allow-list of two**, `awaiting_payment` and `failed`,
+ * and not a negation of `paid`. `deferred` is a credit-limit order whose credit
+ * was drawn inside the placement transaction — the shop is already acting on
+ * it, and there is no buyer-initiated session to open — and `refunded` is
+ * settled in the other direction.
+ *
+ * The lifecycle term is **terminality, not the string `cancelled`**. The status
+ * set is operator-configurable and a deployment may add terminal statuses of
+ * its own, so the question goes to the graph through
+ * `orderTransitionPort.isTerminal`. And the reason it is asked at all is Phase
+ * D's: the ingress no longer writes a terminal status, so a terminal order is
+ * always a deliberate human decision — an administrator's, or the buyer's own —
+ * and paying it again would silently override the person who made it, on stock
+ * the cancellation has already released.
+ */
+/**
+ * The payment states in which the buyer still owes this money themselves
+ * (feature 085, R13's money term).
+ *
+ * An allow-list rather than `!== 'paid'`: `deferred` is a credit-limit order,
+ * unpaid by arrangement and already drawn, and `refunded` is settled the other
+ * way. Both would pass a negation and neither has a session for the buyer to
+ * open.
+ */
+const BUYER_STILL_OWES = new Set([
+    'awaiting_payment',
+    'failed',
+]);
+export class PaymentRetryService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Open (or resume) the buyer's own next payment attempt for `orderId`.
+     *
+     * @throws 404 when the order does not exist or carries no payment attempt.
+     * @throws 403 when the caller did not place the order.
+     * @throws 409 `PAYMENT_NOT_DUE` when the money is not the buyer's to pay —
+     *         the order is paid, drawn against a credit limit, or refunded.
+     * @throws 409 `PAYMENT_ORDER_CLOSED` when the order's lifecycle status is
+     *         terminal. A different condition and so a different code: the money
+     *         may well still be owed, but the order it was owed on is over.
+     * @throws 409 `PAYMENT_ADAPTER_UNAVAILABLE` when the method the order was
+     *         placed with has no adapter registered any more. A third condition,
+     *         and the only one that is about the shop rather than the order.
+     * @throws whatever `assertOrganizationCanTransact` throws for a suspended or
+     *         blocked organisation — the route maps it, exactly as placement does.
+     */
+    async retryForCustomer(input) {
+        const order = await this.deps.orderRead.findById(input.orderId);
+        if (!order) {
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Order not found.');
+        }
+        // Ownership before anything else: keyed on an order id, this route is an
+        // enumeration surface until it has answered "is this yours?".
+        if (order.placedByCustomerAccountId !== input.customerAccountId) {
+            throw new HttpError(403, ERROR_CODES.FORBIDDEN, 'This order does not belong to you.');
+        }
+        if (!BUYER_STILL_OWES.has(order.paymentStatus)) {
+            // The money term, and one code for all three of the statuses it refuses
+            // (`paid`, `deferred`, `refunded`): one predicate, one `throw`, one
+            // sentence the buyer reads either way.
+            //
+            // It answered `VALIDATION_FAILED`, which is worse than an untidy code —
+            // that is the one code `localizeErrorEnvelope` returns *before*
+            // translating (`@endora-commerce/platform/http`), because the code is
+            // overloaded and several services carry machine-readable tokens in its
+            // message. So a buyer read the English written here whatever language
+            // they asked for. The message below is now the raise-site fallback the
+            // envelope substitutes, reached only when no bundle answers.
+            throw new HttpError(409, paymentsErrorCodes.PAYMENT_NOT_DUE, 'This order is not awaiting payment.');
+        }
+        // The lifecycle term (feature 085 Phase D). Asked of the graph, because the
+        // terminal set is operator-configurable — and asked after the money term so
+        // the two refusals stay in the order the buyer's own page explains them in.
+        // `null` is "no such order", which the read above says otherwise; it means
+        // the order was deleted between the two reads, and the attempt this would
+        // open is the one that then answers.
+        if ((await this.deps.orderTransition.isTerminal(order.id)) === true) {
+            // A second code rather than the money term's, because the two terms are
+            // orthogonal and so are the buyer's answers to them: `PAYMENT_NOT_DUE`
+            // says there is nothing to pay, this says the order is over and the
+            // stock its cancellation released is somebody else's now. A buyer who
+            // still wants the goods places a new order; a buyer told the other
+            // sentence does nothing at all.
+            throw new HttpError(409, paymentsErrorCodes.PAYMENT_ORDER_CLOSED, 'This order is closed and can no longer be paid.');
+        }
+        await this.deps.assertOrganizationCanTransact(order.organizationId);
+        const { payment, opened } = await this.deps.paymentService.openRetry(order.id);
+        if (!opened) {
+            // An attempt is already open. Contacting the provider again would be a
+            // second object against one attempt — see `PaymentRetryResult`.
+            return {
+                paymentId: payment.id,
+                attemptNo: payment.attemptNo,
+                opened: false,
+                nextAction: { kind: 'none' },
+            };
+        }
+        const adapterKey = order.paymentMethodSnapshot.adapter;
+        const adapter = adapterKey ? this.deps.paymentAdapterRegistry().get(adapterKey) : undefined;
+        if (!adapter) {
+            await this.deps.paymentService.failAttempt(payment.id, 'No payment adapter is available for this order.');
+            // The third code, and the one refusal here that is not about the order:
+            // it is open, the money is still owed, and the platform cannot start a
+            // session because the adapter the method names is not registered any
+            // more. The buyer's move is to ask the shop, and the shop's is to repair
+            // a configuration — neither of the other two sentences says that.
+            throw new HttpError(409, paymentsErrorCodes.PAYMENT_ADAPTER_UNAVAILABLE, 'The payment method this order was placed with is no longer available.');
+        }
+        const buyer = await this.deps.customerAccountRead.findById(order.placedByCustomerAccountId);
+        const payerName = [buyer?.firstName, buyer?.lastName].filter(Boolean).join(' ').trim() ||
+            order.billingAddress.recipientName ||
+            buyer?.email ||
+            null;
+        let started;
+        try {
+            const result = await adapter.onStorefrontOrderCreated({
+                orderId: order.id,
+                paymentId: payment.id,
+                amount: Number(payment.amount),
+                currency: payment.currency,
+                paymentMethodCode: order.paymentMethodSnapshot.code,
+                paymentMethodId: order.paymentMethodId,
+                salesChannelId: order.salesChannelId,
+                payerEmail: buyer?.email ?? null,
+                payerName,
+                billingCountry: order.billingAddress.country ?? null,
+                orderBusinessId: order.businessId,
+            });
+            started = result;
+        }
+        catch (error) {
+            // A narrow, compensating tolerance, and the one shape the checklist
+            // endorses: the attempt row is written before the adapter can be asked
+            // (it needs the id), so an adapter that refuses must not leave an open
+            // attempt no provider knows about — the buyer's next click would resume
+            // that phantom instead of opening a real attempt. The failure is
+            // re-thrown; only the row is repaired.
+            rethrowIfModuleDisabled(error);
+            await this.deps.paymentService.failAttempt(payment.id, error instanceof Error ? error.message : 'The payment could not be started.');
+            throw error;
+        }
+        return {
+            paymentId: payment.id,
+            attemptNo: payment.attemptNo,
+            opened: true,
+            nextAction: started,
+        };
+    }
+}
+//# sourceMappingURL=payment-retry-service.js.map

package/dist/backend/services/payment-retry-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-retry-service.js","sourceRoot":"","sources":["../../../src/backend/services/payment-retry-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/payment-service.d.ts

@@ -0,0 +1,62 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type OrderReadPort } from '@endora-commerce/contracts';
+import { Payment } from '../entities/payment.entity.js';
+/**
+ * The two things "open a retry" can mean, kept apart because they are the
+ * difference between contacting a provider and not (issue #264).
+ *
+ * `opened: true` is a new attempt row — the previous one had failed, so the
+ * next `attemptNo` is the record a fresh provider session will settle.
+ * `opened: false` is the attempt that was already open being handed back
+ * unchanged: a second click, a reload, a buyer returning to a payment they
+ * walked away from. The caller must not start a provider session for it.
+ */
+export interface OpenRetryResult {
+    payment: Payment;
+    opened: boolean;
+}
+/**
+ * PaymentService (feature 034, FR-024) — opens retry Payments. The first
+ * Payment of an order is created by OrderService.placeOrder; a retry opens a
+ * new row against the same order with the next `attemptNo`, leaving prior
+ * (failed) attempts intact so the admin can see the full history.
+ *
+ * **A fresh attempt row is what makes a gateway able to start over**
+ * (issue #264), which is why the customer-facing retry runs through here rather
+ * than re-driving the failed row. Every gateway keys its own object on this
+ * platform's payment id: PayU sends it as `extOrderId`, which must be unique
+ * per POS; TPay resolves the newest `tpay_transactions` row for the order;
+ * Stripe records a `stripe_payment_intents` mapping per payment. Re-using the
+ * failed attempt asks all four to open a second session against an identifier
+ * they have already spent.
+ */
+export declare class PaymentService {
+    #private;
+    private readonly emFactory;
+    private readonly orderRead;
+    constructor(emFactory: () => EntityManager, orderRead: OrderReadPort);
+    /**
+     * The next attempt for `orderId`, opening one only when the latest has
+     * failed.
+     *
+     * The latest attempt is read `FOR UPDATE`, so two callers racing on the same
+     * order serialise here and the second sees what the first wrote: a buyer
+     * double-clicking gets one new attempt, not two. It is the same row the
+     * settlement ingress resolves, so a retry and a late gateway callback cannot
+     * interleave halfway through each other.
+     */
+    openRetry(orderId: string): Promise<OpenRetryResult>;
+    /**
+     * Close an attempt whose provider session could not be started.
+     *
+     * The compensating half of {@link openRetry}: the row is written before the
+     * adapter is asked (the adapter needs its id), so an adapter that throws
+     * would otherwise leave an `awaiting_payment` attempt no provider knows
+     * about — and the next retry would *resume* that phantom instead of opening a
+     * real one. Marking it failed puts the order back where the buyer can try
+     * again.
+     */
+    failAttempt(paymentId: string, reason: string): Promise<void>;
+    listForOrder(orderId: string): Promise<Payment[]>;
+}
+//# sourceMappingURL=payment-service.d.ts.map

package/dist/backend/services/payment-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/payment-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;;IAEvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,SAAS,EAAE,MAAM,aAAa,EAC9B,SAAS,EAAE,aAAa;IAkC3C;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAkD1D;;;;;;;;;OASG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAKxD"}