@open-mercato/core 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/dist/modules/payment_gateways/lib/capture-ledger.js

@@ -0,0 +1,183 @@
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { GatewayPaymentOperation, GatewayTransaction } from "../data/entities.js";
+const AMOUNT_SCALE = 4;
+const AMOUNT_UNITS_PER_WHOLE = 10n ** BigInt(AMOUNT_SCALE);
+const DECIMAL_PATTERN = /^(-?)(\d*)(?:\.(\d*))?$/;
+function parseAmountUnits(value) {
+  if (value === null || value === void 0) return 0n;
+  const text = typeof value === "number" ? value.toFixed(AMOUNT_SCALE) : value.trim();
+  const match = DECIMAL_PATTERN.exec(text);
+  const whole = match?.[2] ?? "";
+  const fraction = match?.[3] ?? "";
+  if (!match || whole === "" && fraction === "") {
+    throw new Error(`[internal] Unsupported gateway amount value: ${String(value)}`);
+  }
+  const keptFraction = fraction.slice(0, AMOUNT_SCALE).padEnd(AMOUNT_SCALE, "0");
+  const nextDigit = fraction.charAt(AMOUNT_SCALE);
+  let units = BigInt(whole === "" ? "0" : whole) * AMOUNT_UNITS_PER_WHOLE + BigInt(keptFraction);
+  if (nextDigit !== "" && Number(nextDigit) >= 5) units += 1n;
+  return match[1] === "-" ? -units : units;
+}
+function formatAmountUnits(units) {
+  const negative = units < 0n;
+  const absolute = negative ? -units : units;
+  const fraction = (absolute % AMOUNT_UNITS_PER_WHOLE).toString().padStart(AMOUNT_SCALE, "0");
+  return `${negative ? "-" : ""}${absolute / AMOUNT_UNITS_PER_WHOLE}.${fraction}`;
+}
+function formatAmountLabel(units) {
+  return formatAmountUnits(units).replace(/\.?0+$/, "");
+}
+function captureConflict(code, message) {
+  return new CrudHttpError(409, { error: message, code });
+}
+function resolveCaptureAmounts(transaction, amount) {
+  const authorizedUnits = parseAmountUnits(transaction.amount);
+  const capturedUnits = parseAmountUnits(transaction.capturedAmount);
+  const remainingUnits = authorizedUnits - capturedUnits;
+  return {
+    authorizedUnits,
+    capturedUnits,
+    remainingUnits,
+    requestedUnits: amount === void 0 ? remainingUnits : parseAmountUnits(amount)
+  };
+}
+function assertCaptureWithinRemaining(transaction, amount) {
+  const amounts = resolveCaptureAmounts(transaction, amount);
+  if (amounts.remainingUnits <= 0n) {
+    throw captureConflict(
+      "payment_capture_ceiling_exceeded",
+      `Transaction is already fully captured (${formatAmountLabel(amounts.capturedUnits)} of ${formatAmountLabel(amounts.authorizedUnits)})`
+    );
+  }
+  if (amounts.requestedUnits <= 0n) {
+    throw captureConflict("payment_capture_amount_invalid", "Capture amount must be greater than zero");
+  }
+  if (amounts.requestedUnits > amounts.remainingUnits) {
+    throw captureConflict(
+      "payment_capture_ceiling_exceeded",
+      `Capture amount ${formatAmountLabel(amounts.requestedUnits)} exceeds the ${formatAmountLabel(amounts.remainingUnits)} still capturable on authorized amount ${formatAmountLabel(amounts.authorizedUnits)} (already captured ${formatAmountLabel(amounts.capturedUnits)})`
+    );
+  }
+  return amounts;
+}
+async function reserveCaptureAmount(em, input) {
+  if (input.operation.reservedAmount !== null && input.operation.reservedAmount !== void 0) {
+    return parseAmountUnits(input.operation.reservedAmount);
+  }
+  const amounts = assertCaptureWithinRemaining(input.transaction, input.amount);
+  const previousCapturedAmount = input.transaction.capturedAmount;
+  const reservedAmount = formatAmountUnits(amounts.requestedUnits);
+  const nextCapturedAmount = formatAmountUnits(amounts.capturedUnits + amounts.requestedUnits);
+  await em.transactional(async (tx) => {
+    const reserved = await tx.nativeUpdate(
+      GatewayTransaction,
+      {
+        id: input.transaction.id,
+        organizationId: input.scope.organizationId,
+        tenantId: input.scope.tenantId,
+        deletedAt: null,
+        capturedAmount: previousCapturedAmount
+      },
+      { capturedAmount: nextCapturedAmount, updatedAt: /* @__PURE__ */ new Date() }
+    );
+    if (reserved !== 1) {
+      throw captureConflict(
+        "payment_capture_reservation_conflict",
+        "This transaction changed while the capture amount was being reserved; re-read it and retry with the remaining amount"
+      );
+    }
+    const stamped = await tx.nativeUpdate(
+      GatewayPaymentOperation,
+      {
+        id: input.operation.id,
+        organizationId: input.scope.organizationId,
+        tenantId: input.scope.tenantId,
+        reservedAmount: null
+      },
+      { reservedAmount, updatedAt: /* @__PURE__ */ new Date() }
+    );
+    if (stamped !== 1) {
+      throw captureConflict(
+        "payment_capture_reservation_conflict",
+        "Capture reservation could not be recorded for this operation"
+      );
+    }
+  });
+  Object.assign(input.operation, { reservedAmount });
+  return amounts.requestedUnits;
+}
+function settleCapturedAmount(transaction, reservedUnits, capturedAmount) {
+  const actualUnits = typeof capturedAmount === "number" && Number.isFinite(capturedAmount) && capturedAmount >= 0 ? parseAmountUnits(capturedAmount) : reservedUnits;
+  if (actualUnits === reservedUnits) return;
+  const settledUnits = parseAmountUnits(transaction.capturedAmount) - reservedUnits + actualUnits;
+  transaction.capturedAmount = formatAmountUnits(settledUnits < 0n ? 0n : settledUnits);
+}
+function alignCapturedAmountWithStatus(transaction, status) {
+  if (status !== "captured") return;
+  const authorizedUnits = parseAmountUnits(transaction.amount);
+  if (parseAmountUnits(transaction.capturedAmount) >= authorizedUnits) return;
+  transaction.capturedAmount = formatAmountUnits(authorizedUnits);
+}
+async function releaseCaptureAmount(em, input) {
+  const reservedAmount = formatAmountUnits(input.reservedUnits);
+  try {
+    return await em.transactional(async (tx) => {
+      const current = await findOneWithDecryption(
+        tx,
+        GatewayTransaction,
+        {
+          id: input.transactionId,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId
+        },
+        void 0,
+        input.scope
+      );
+      if (!current) return false;
+      const releasedUnits = parseAmountUnits(current.capturedAmount) - input.reservedUnits;
+      const released = await tx.nativeUpdate(
+        GatewayTransaction,
+        {
+          id: input.transactionId,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId,
+          capturedAmount: current.capturedAmount
+        },
+        { capturedAmount: formatAmountUnits(releasedUnits < 0n ? 0n : releasedUnits), updatedAt: /* @__PURE__ */ new Date() }
+      );
+      if (released !== 1) return false;
+      const cleared = await tx.nativeUpdate(
+        GatewayPaymentOperation,
+        {
+          id: input.operation.id,
+          organizationId: input.scope.organizationId,
+          tenantId: input.scope.tenantId,
+          reservedAmount
+        },
+        { reservedAmount: null, updatedAt: /* @__PURE__ */ new Date() }
+      );
+      if (cleared !== 1) {
+        throw captureConflict(
+          "payment_capture_reservation_conflict",
+          "Capture reservation could not be released for this operation"
+        );
+      }
+      Object.assign(input.operation, { reservedAmount: null });
+      return true;
+    });
+  } catch {
+    return false;
+  }
+}
+export {
+  alignCapturedAmountWithStatus,
+  assertCaptureWithinRemaining,
+  formatAmountUnits,
+  parseAmountUnits,
+  releaseCaptureAmount,
+  reserveCaptureAmount,
+  resolveCaptureAmounts,
+  settleCapturedAmount
+};
+//# sourceMappingURL=capture-ledger.js.map

package/dist/modules/payment_gateways/lib/capture-ledger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/payment_gateways/lib/capture-ledger.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport type { UnifiedPaymentStatus } from '@open-mercato/shared/modules/payment_gateways/types'\nimport { GatewayPaymentOperation, GatewayTransaction } from '../data/entities'\n\ntype Scope = { organizationId: string; tenantId: string }\n\nconst AMOUNT_SCALE = 4\nconst AMOUNT_UNITS_PER_WHOLE = 10n ** BigInt(AMOUNT_SCALE)\nconst DECIMAL_PATTERN = /^(-?)(\\d*)(?:\\.(\\d*))?$/\n\n/**\n * Money in this module lives in `numeric(18,4)` columns and is read back as strings. Every\n * comparison and every sum runs on integer minor units (1 unit = 10^-4) so partial captures\n * never accumulate floating-point drift. Extra precision beyond four decimals is rounded\n * half-up, matching what Postgres would store in the column anyway.\n */\nexport function parseAmountUnits(value: string | number | null | undefined): bigint {\n  if (value === null || value === undefined) return 0n\n  const text = typeof value === 'number' ? value.toFixed(AMOUNT_SCALE) : value.trim()\n  const match = DECIMAL_PATTERN.exec(text)\n  const whole = match?.[2] ?? ''\n  const fraction = match?.[3] ?? ''\n  if (!match || (whole === '' && fraction === '')) {\n    throw new Error(`[internal] Unsupported gateway amount value: ${String(value)}`)\n  }\n  const keptFraction = fraction.slice(0, AMOUNT_SCALE).padEnd(AMOUNT_SCALE, '0')\n  const nextDigit = fraction.charAt(AMOUNT_SCALE)\n  let units = BigInt(whole === '' ? '0' : whole) * AMOUNT_UNITS_PER_WHOLE + BigInt(keptFraction)\n  if (nextDigit !== '' && Number(nextDigit) >= 5) units += 1n\n  return match[1] === '-' ? -units : units\n}\n\nexport function formatAmountUnits(units: bigint): string {\n  const negative = units < 0n\n  const absolute = negative ? -units : units\n  const fraction = (absolute % AMOUNT_UNITS_PER_WHOLE).toString().padStart(AMOUNT_SCALE, '0')\n  return `${negative ? '-' : ''}${absolute / AMOUNT_UNITS_PER_WHOLE}.${fraction}`\n}\n\nfunction formatAmountLabel(units: bigint): string {\n  return formatAmountUnits(units).replace(/\\.?0+$/, '')\n}\n\nfunction captureConflict(code: string, message: string): CrudHttpError {\n  return new CrudHttpError(409, { error: message, code })\n}\n\nexport type CaptureAmounts = {\n  authorizedUnits: bigint\n  capturedUnits: bigint\n  remainingUnits: bigint\n  requestedUnits: bigint\n}\n\n/**\n * Resolves what a capture request means for the transaction's running total. An omitted\n * amount captures everything that is still authorized, not the original full amount.\n */\nexport function resolveCaptureAmounts(transaction: GatewayTransaction, amount: number | undefined): CaptureAmounts {\n  const authorizedUnits = parseAmountUnits(transaction.amount)\n  const capturedUnits = parseAmountUnits(transaction.capturedAmount)\n  const remainingUnits = authorizedUnits - capturedUnits\n  return {\n    authorizedUnits,\n    capturedUnits,\n    remainingUnits,\n    requestedUnits: amount === undefined ? remainingUnits : parseAmountUnits(amount),\n  }\n}\n\n/**\n * Rejects a capture whose amount would push the captured-to-date total past the authorized\n * amount. This is the cumulative ceiling: each individual request may look small, but the\n * sum of all captures against one authorization can never exceed it (#4487).\n */\nexport function assertCaptureWithinRemaining(\n  transaction: GatewayTransaction,\n  amount: number | undefined,\n): CaptureAmounts {\n  const amounts = resolveCaptureAmounts(transaction, amount)\n  if (amounts.remainingUnits <= 0n) {\n    throw captureConflict(\n      'payment_capture_ceiling_exceeded',\n      `Transaction is already fully captured (${formatAmountLabel(amounts.capturedUnits)} of ${formatAmountLabel(amounts.authorizedUnits)})`,\n    )\n  }\n  if (amounts.requestedUnits <= 0n) {\n    throw captureConflict('payment_capture_amount_invalid', 'Capture amount must be greater than zero')\n  }\n  if (amounts.requestedUnits > amounts.remainingUnits) {\n    throw captureConflict(\n      'payment_capture_ceiling_exceeded',\n      `Capture amount ${formatAmountLabel(amounts.requestedUnits)} exceeds the ${formatAmountLabel(amounts.remainingUnits)} still capturable on authorized amount ${formatAmountLabel(amounts.authorizedUnits)} (already captured ${formatAmountLabel(amounts.capturedUnits)})`,\n    )\n  }\n  return amounts\n}\n\n/**\n * Claims the requested slice of the authorized amount before the provider is called, so two\n * concurrent captures can never both charge. The increment is a compare-and-swap on the\n * previous captured-to-date value: whoever loses it never reaches the adapter. The reserved\n * amount is stamped on the operation row in the same transaction, so a retry of the same\n * operation id reuses its reservation instead of reserving twice.\n */\nexport async function reserveCaptureAmount(em: EntityManager, input: {\n  transaction: GatewayTransaction\n  operation: GatewayPaymentOperation\n  amount: number | undefined\n  scope: Scope\n}): Promise<bigint> {\n  if (input.operation.reservedAmount !== null && input.operation.reservedAmount !== undefined) {\n    return parseAmountUnits(input.operation.reservedAmount)\n  }\n  const amounts = assertCaptureWithinRemaining(input.transaction, input.amount)\n  const previousCapturedAmount = input.transaction.capturedAmount\n  const reservedAmount = formatAmountUnits(amounts.requestedUnits)\n  const nextCapturedAmount = formatAmountUnits(amounts.capturedUnits + amounts.requestedUnits)\n\n  await em.transactional(async (tx) => {\n    const reserved = await tx.nativeUpdate(\n      GatewayTransaction,\n      {\n        id: input.transaction.id,\n        organizationId: input.scope.organizationId,\n        tenantId: input.scope.tenantId,\n        deletedAt: null,\n        capturedAmount: previousCapturedAmount,\n      },\n      { capturedAmount: nextCapturedAmount, updatedAt: new Date() },\n    )\n    if (reserved !== 1) {\n      throw captureConflict(\n        'payment_capture_reservation_conflict',\n        'This transaction changed while the capture amount was being reserved; re-read it and retry with the remaining amount',\n      )\n    }\n    const stamped = await tx.nativeUpdate(\n      GatewayPaymentOperation,\n      {\n        id: input.operation.id,\n        organizationId: input.scope.organizationId,\n        tenantId: input.scope.tenantId,\n        reservedAmount: null,\n      },\n      { reservedAmount, updatedAt: new Date() },\n    )\n    if (stamped !== 1) {\n      throw captureConflict(\n        'payment_capture_reservation_conflict',\n        'Capture reservation could not be recorded for this operation',\n      )\n    }\n  })\n\n  Object.assign(input.operation, { reservedAmount })\n  return amounts.requestedUnits\n}\n\n/**\n * Reconciles the reservation with what the provider actually captured. Runs on the transaction\n * instance loaded inside the completion transaction, so the adjustment commits together with\n * the operation result.\n */\nexport function settleCapturedAmount(\n  transaction: GatewayTransaction,\n  reservedUnits: bigint,\n  capturedAmount: number | undefined,\n): void {\n  const actualUnits = typeof capturedAmount === 'number' && Number.isFinite(capturedAmount) && capturedAmount >= 0\n    ? parseAmountUnits(capturedAmount)\n    : reservedUnits\n  if (actualUnits === reservedUnits) return\n  const settledUnits = parseAmountUnits(transaction.capturedAmount) - reservedUnits + actualUnits\n  transaction.capturedAmount = formatAmountUnits(settledUnits < 0n ? 0n : settledUnits)\n}\n\n/**\n * Keeps the ledger honest for captures that happened outside the capture endpoint. A webhook or a\n * status poll reports money that already moved but carries no captured amount, so only `captured`\n * \u2014 the provider saying the whole authorization was taken \u2014 can be translated into a number: the\n * full amount. The ledger is raised, never lowered, so an already recorded capture survives.\n * `partially_captured` carries no recoverable amount, so it is left alone and the remainder stays\n * capturable.\n */\nexport function alignCapturedAmountWithStatus(\n  transaction: GatewayTransaction,\n  status: UnifiedPaymentStatus,\n): void {\n  if (status !== 'captured') return\n  const authorizedUnits = parseAmountUnits(transaction.amount)\n  if (parseAmountUnits(transaction.capturedAmount) >= authorizedUnits) return\n  transaction.capturedAmount = formatAmountUnits(authorizedUnits)\n}\n\n/**\n * Gives the reserved slice back after a failed provider call. Both writes share one\n * transaction, so a partial release is impossible: either the amount becomes capturable again\n * and the operation stops holding it, or the reservation stays outstanding. Returning `false`\n * means the reservation is still held \u2014 the conservative outcome when it is unknown whether\n * the provider took the money.\n */\nexport async function releaseCaptureAmount(em: EntityManager, input: {\n  transactionId: string\n  operation: GatewayPaymentOperation\n  reservedUnits: bigint\n  scope: Scope\n}): Promise<boolean> {\n  const reservedAmount = formatAmountUnits(input.reservedUnits)\n  try {\n    return await em.transactional(async (tx) => {\n      const current = await findOneWithDecryption(\n        tx,\n        GatewayTransaction,\n        {\n          id: input.transactionId,\n          organizationId: input.scope.organizationId,\n          tenantId: input.scope.tenantId,\n        },\n        undefined,\n        input.scope,\n      )\n      if (!current) return false\n      const releasedUnits = parseAmountUnits(current.capturedAmount) - input.reservedUnits\n      const released = await tx.nativeUpdate(\n        GatewayTransaction,\n        {\n          id: input.transactionId,\n          organizationId: input.scope.organizationId,\n          tenantId: input.scope.tenantId,\n          capturedAmount: current.capturedAmount,\n        },\n        { capturedAmount: formatAmountUnits(releasedUnits < 0n ? 0n : releasedUnits), updatedAt: new Date() },\n      )\n      if (released !== 1) return false\n      const cleared = await tx.nativeUpdate(\n        GatewayPaymentOperation,\n        {\n          id: input.operation.id,\n          organizationId: input.scope.organizationId,\n          tenantId: input.scope.tenantId,\n          reservedAmount,\n        },\n        { reservedAmount: null, updatedAt: new Date() },\n      )\n      if (cleared !== 1) {\n        throw captureConflict(\n          'payment_capture_reservation_conflict',\n          'Capture reservation could not be released for this operation',\n        )\n      }\n      Object.assign(input.operation, { reservedAmount: null })\n      return true\n    })\n  } catch {\n    return false\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/payment_gateways/lib/gateway-service.js

@@ -1,13 +1,24 @@
 import { randomUUID } from "node:crypto";
 import { findOneWithDecryption, findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { createLogger } from "@open-mercato/shared/lib/logger";
 import {
   getGatewayAdapter
 } from "@open-mercato/shared/modules/payment_gateways/types";
-import { conflict } from "@open-mercato/shared/lib/crud/errors";
+import { conflict, CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
 import { GatewaySessionInitialization, GatewayTransaction } from "../data/entities.js";
 import { canApplyManualAction, isValidTransition } from "./status-machine.js";
 import { emitPaymentGatewayEvent } from "../events.js";
 import { readGatewayMetadata, readWebhookLog } from "./transaction-fields.js";
+import { reconcileSessionAmountWithOrder } from "./order-amount-reconciliation.js";
+import {
+  alignCapturedAmountWithStatus,
+  assertCaptureWithinRemaining,
+  formatAmountUnits,
+  parseAmountUnits,
+  releaseCaptureAmount,
+  reserveCaptureAmount,
+  settleCapturedAmount
+} from "./capture-ledger.js";
 import {
   completePaymentOperation,
   failPaymentOperation,
@@ -23,17 +34,13 @@ import {
 } from "./session-idempotency.js";
 const PAYMENT_SESSION_CLAIM_STALE_MS = 3e4;
 const PAYMENT_SESSION_WAIT_INTERVAL_MS = 25;
+const logger = createLogger("payment_gateways").child({ component: "gateway-service" });
 function assertManualActionAllowed(action, transaction) {
   const current = transaction.unifiedStatus;
   if (!canApplyManualAction(action, current)) {
     throw conflict(`Cannot ${action} a payment in status "${current}"`);
   }
 }
-function assertCaptureAmountAllowed(amount, transaction) {
-  if (amount !== void 0 && amount > Number(transaction.amount)) {
-    throw conflict(`Capture amount ${amount} exceeds authorized transaction amount ${transaction.amount}`);
-  }
-}
 function applyAdapterResultStatus(action, transaction, resultStatus) {
   const current = transaction.unifiedStatus;
   if (resultStatus === current) return false;
@@ -107,9 +114,8 @@ function createPaymentGatewayService(deps) {
     const selectedVersion = deps.integrationStateService ? await deps.integrationStateService.resolveApiVersion(integrationId, scope) : void 0;
     const adapter = getGatewayAdapter(providerKey, selectedVersion);
     if (!adapter) {
-      throw new Error(
-        selectedVersion ? `No gateway adapter registered for provider: ${providerKey} (version: ${selectedVersion})` : `No gateway adapter registered for provider: ${providerKey}`
-      );
+      const message = selectedVersion ? `No gateway adapter registered for provider: ${providerKey} (version: ${selectedVersion})` : `No gateway adapter registered for provider: ${providerKey}`;
+      throw new CrudHttpError(422, { error: message });
     }
     const credentials = await integrationCredentialsService.resolve(integrationId, scope) ?? {};
     return { adapter, credentials };
@@ -137,7 +143,11 @@ function createPaymentGatewayService(deps) {
       }
       return prepared.result;
     }
+    const operation = prepared.claim.record;
+    let settled = false;
+    let providerInvoked = false;
     try {
+      await input.beforeInvoke?.({ transaction, operation });
       const { adapter, credentials } = await resolveAdapterAndCredentials(
         transaction.providerKey,
         { organizationId: transaction.organizationId, tenantId: transaction.tenantId }
@@ -148,6 +158,7 @@ function createPaymentGatewayService(deps) {
         transaction,
         idempotencyKey: prepared.claim.providerIdempotencyKey
       });
+      providerInvoked = true;
       const statusChanged = await completePaymentOperation(
         em,
         prepared.claim,
@@ -159,6 +170,7 @@ function createPaymentGatewayService(deps) {
           return changed;
         }
       );
+      settled = true;
       if (statusChanged) {
         await emitStatusEvent(result.status, {
           transactionId: transaction.id,
@@ -171,7 +183,12 @@ function createPaymentGatewayService(deps) {
       await input.afterCommit(transaction, result);
       return result;
     } catch (error) {
-      await Promise.allSettled([failPaymentOperation(em, prepared.claim)]);
+      if (!settled) {
+        if (input.releaseOnFailure) {
+          await input.releaseOnFailure({ transaction, operation, providerInvoked }).catch(() => void 0);
+        }
+        await Promise.allSettled([failPaymentOperation(em, prepared.claim)]);
+      }
       throw error;
     }
   }
@@ -184,6 +201,9 @@ function createPaymentGatewayService(deps) {
       redirectUrl: session.redirectUrl ?? (session.clientSession?.type === "redirect" ? session.clientSession.redirectUrl : null),
       clientSecret: session.clientSecret ?? null,
       amount: String(input.amount),
+      // An automatic-capture session comes back already captured, so the ledger has to start
+      // at the full amount — otherwise a later manual capture would look like the first one.
+      capturedAmount: session.status === "captured" ? String(input.amount) : "0",
       currencyCode: input.currencyCode,
       gatewayMetadata: {
         ...session.providerData ?? {},
@@ -257,6 +277,13 @@ function createPaymentGatewayService(deps) {
   return {
     async createPaymentSession(input) {
       const scope = { organizationId: input.organizationId, tenantId: input.tenantId };
+      await reconcileSessionAmountWithOrder({
+        orderId: input.orderId,
+        amount: input.amount,
+        currencyCode: input.currencyCode,
+        scope,
+        resolver: deps.paymentOrderTotalResolver
+      });
       const { adapter, credentials } = await resolveAdapterAndCredentials(input.providerKey, scope);
       const sessionInput = {
         paymentId: input.paymentId,
@@ -304,7 +331,7 @@ function createPaymentGatewayService(deps) {
             scope
           );
           if (!transaction2) {
-            throw new Error("Completed payment session is missing its gateway transaction");
+            throw new Error("[internal] Completed payment session is missing its gateway transaction");
           }
           return { transaction: transaction2, session: restoreSession(transaction2) };
         }
@@ -320,7 +347,15 @@ function createPaymentGatewayService(deps) {
         try {
           session = await adapter.createSession({ ...sessionInput, idempotencyKey: operationKey });
         } catch (error) {
-          await releasePaymentSessionInitialization(em, ownership, scope).catch(() => void 0);
+          try {
+            await releasePaymentSessionInitialization(em, ownership, scope);
+          } catch (releaseError) {
+            logger.warn("Failed to release payment session initialization claim", {
+              claimId: ownership.id,
+              providerKey: input.providerKey,
+              err: releaseError
+            });
+          }
           throw error;
         } finally {
           await stopHeartbeat();
@@ -356,16 +391,57 @@ function createPaymentGatewayService(deps) {
       }
     },
     async capturePayment(transactionId, amount, scope, operationId) {
+      let reservedUnits = null;
+      let providerAmount = amount;
       return executeManualOperation({
         action: "capture",
         transactionId,
         operationId,
         payload: { amount: amount ?? null },
         scope,
-        assertInitialAllowed: (transaction) => assertCaptureAmountAllowed(amount, transaction),
+        assertInitialAllowed: (transaction) => {
+          assertCaptureWithinRemaining(transaction, amount);
+        },
+        beforeInvoke: async ({ transaction, operation }) => {
+          const alreadyCapturedUnits = parseAmountUnits(transaction.capturedAmount);
+          reservedUnits = await reserveCaptureAmount(em, { transaction, operation, amount, scope });
+          if (amount === void 0 && alreadyCapturedUnits > 0n) {
+            providerAmount = Number(formatAmountUnits(reservedUnits));
+          }
+        },
+        // The slice goes back only while the provider has not been called yet. Once the capture
+        // call returned, the money may already have moved and only the completion transaction
+        // failed, so releasing would reopen the authorization for a fresh operation id and allow an
+        // over-capture. Holding the reservation is the conservative outcome: a retry of this same
+        // operation id reuses both the reservation and the provider idempotency key, so the provider
+        // itself collapses the duplicate.
+        releaseOnFailure: async ({ transaction, operation, providerInvoked }) => {
+          if (reservedUnits === null) return;
+          if (providerInvoked) {
+            await writeTransactionLog(
+              transaction.providerKey,
+              { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+              transaction.id,
+              "warn",
+              "Capture reservation stays outstanding because the provider call already returned",
+              { operationId: operation.operationId, reservedAmount: formatAmountUnits(reservedUnits) }
+            );
+            return;
+          }
+          const released = await releaseCaptureAmount(em, { transactionId, operation, reservedUnits, scope });
+          if (released) return;
+          await writeTransactionLog(
+            transaction.providerKey,
+            { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
+            transaction.id,
+            "warn",
+            "Capture reservation stays outstanding after a failed capture",
+            { operationId: operation.operationId, reservedAmount: formatAmountUnits(reservedUnits) }
+          );
+        },
         invoke: ({ adapter, credentials, transaction, idempotencyKey }) => adapter.capture({
           sessionId: readProviderSessionId(transaction),
-          amount,
+          amount: providerAmount,
           credentials,
           idempotencyKey
         }),
@@ -374,6 +450,7 @@ function createPaymentGatewayService(deps) {
             ...readGatewayMetadata(transaction.gatewayMetadata),
             captureResult: result.providerData
           };
+          if (reservedUnits !== null) settleCapturedAmount(transaction, reservedUnits, result.capturedAmount);
         },
         afterCommit: (transaction, result) => writeTransactionLog(
           transaction.providerKey,
@@ -454,6 +531,7 @@ function createPaymentGatewayService(deps) {
       if (status.status !== transaction.unifiedStatus && isValidTransition(transaction.unifiedStatus, status.status)) {
         const previousStatus = transaction.unifiedStatus;
         transaction.unifiedStatus = status.status;
+        alignCapturedAmountWithStatus(transaction, status.status);
         transaction.gatewayStatus = status.status;
         transaction.gatewayMetadata = { ...readGatewayMetadata(transaction.gatewayMetadata), statusResult: status.providerData ?? null };
         transaction.lastPolledAt = /* @__PURE__ */ new Date();
@@ -488,6 +566,7 @@ function createPaymentGatewayService(deps) {
       const previousStatus = transaction.unifiedStatus;
       if (shouldApplyStatus) {
         transaction.unifiedStatus = update.unifiedStatus;
+        alignCapturedAmountWithStatus(transaction, update.unifiedStatus);
       }
       if (update.providerStatus) {
         transaction.gatewayStatus = update.providerStatus;