@open-mercato/core 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/src/modules/payment_gateways/di.ts

@@ -4,9 +4,11 @@ import type { AppContainer } from '@open-mercato/shared/lib/di/container'
 import type { CredentialsService } from '../integrations/lib/credentials-service'
 import type { IntegrationLogService } from '../integrations/lib/log-service'
 import type { IntegrationStateService } from '../integrations/lib/state-service'
+import type { PaymentOrderTotalResolver } from '@open-mercato/shared/modules/payment_gateways/types'
 import { GatewayTransaction, WebhookProcessedEvent } from './data/entities'
 import { createPaymentGatewayDescriptorService } from './lib/descriptor-service'
 import { createPaymentGatewayService } from './lib/gateway-service'
+import { isPaymentOrderTotalResolver } from './lib/order-amount-reconciliation'
 
 type Cradle = {
   em: EntityManager
@@ -15,10 +17,34 @@ type Cradle = {
   integrationStateService: IntegrationStateService
 }
 
+const ORDER_TOTAL_RESOLVER_NAME = 'paymentOrderTotalResolver'
+
+/**
+ * The order-total resolver is owned by whichever module owns orders (`sales`
+ * registers the default one). Its absence is the only supported reason to skip
+ * amount reconciliation, so this only tolerates a missing registration: a
+ * registered resolver that fails to build or does not satisfy the contract
+ * throws instead of silently disabling the check.
+ */
+function resolveOrderTotalResolver(container: AppContainer, cradle: Cradle): PaymentOrderTotalResolver | null {
+  if (!container.hasRegistration(ORDER_TOTAL_RESOLVER_NAME)) return null
+  const candidate = (cradle as Cradle & { paymentOrderTotalResolver?: unknown })[ORDER_TOTAL_RESOLVER_NAME]
+  if (!isPaymentOrderTotalResolver(candidate)) {
+    throw new Error(`[internal] ${ORDER_TOTAL_RESOLVER_NAME} does not implement resolveOrderTotal`)
+  }
+  return candidate
+}
+
 export function register(container: AppContainer) {
   container.register({
-    paymentGatewayService: asFunction(({ em, integrationCredentialsService, integrationLogService, integrationStateService }: Cradle) =>
-      createPaymentGatewayService({ em, integrationCredentialsService, integrationLogService, integrationStateService }),
+    paymentGatewayService: asFunction((cradle: Cradle) =>
+      createPaymentGatewayService({
+        em: cradle.em,
+        integrationCredentialsService: cradle.integrationCredentialsService,
+        integrationLogService: cradle.integrationLogService,
+        integrationStateService: cradle.integrationStateService,
+        paymentOrderTotalResolver: resolveOrderTotalResolver(container, cradle),
+      }),
     ).scoped().proxy(),
     paymentGatewayDescriptorService: asFunction(({ integrationCredentialsService, integrationStateService }: Cradle) =>
       createPaymentGatewayDescriptorService({ integrationCredentialsService, integrationStateService }),

package/src/modules/payment_gateways/extension-points.ts

@@ -0,0 +1,16 @@
+import { dataTableExtensionHost, defineModuleExtensionPoints, injectionExtensionHost } from '@open-mercato/shared/modules/widgets/extension-points'
+
+export const extensionPoints = defineModuleExtensionPoints({
+  moduleId: 'payment_gateways',
+  hosts: {
+    transactionsTable: dataTableExtensionHost({ tableId: 'payment_gateways.transactions.list', source: 'backend/payment-gateways/page.tsx' }),
+    transactionsAfter: injectionExtensionHost({
+      family: 'detail',
+      spotId: 'admin.page:payment-gateways/transactions:after',
+      supported: ['render-widget'],
+      source: 'backend/payment-gateways/page.tsx',
+    }),
+  },
+})
+
+export default extensionPoints

package/src/modules/payment_gateways/i18n/de.json

@@ -2,6 +2,9 @@
   "payment_gateways.captureMethod.automatic": "Automatisch",
   "payment_gateways.captureMethod.manual": "Manuell",
   "payment_gateways.column.gatewayStatus": "Gateway-Status",
+  "payment_gateways.errors.sessionAmountMismatch": "Der Betrag der Zahlungssitzung {amount} stimmt nicht mit dem fälligen Betrag der Bestellung {orderId} überein",
+  "payment_gateways.errors.sessionCurrencyMismatch": "Die Währung der Zahlungssitzung {currencyCode} stimmt nicht mit der Währung der Bestellung {orderId} überein",
+  "payment_gateways.errors.sessionOrderNotFound": "Bestellung {orderId} wurde im aktuellen Gültigkeitsbereich nicht gefunden",
   "payment_gateways.feature.capture": "Autorisierte Zahlungen erfassen",
   "payment_gateways.feature.manage": "Zahlungssitzungen verwalten",
   "payment_gateways.feature.refund": "Erfasste Zahlungen erstatten",
@@ -76,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Payment erfasst",
   "payment_gateways.transactions.success.refreshStatus": "Der Transaktionsstatus wurde aktualisiert",
   "payment_gateways.transactions.tableTitle": "Transaktionen",
-  "payment_gateways.transactions.title": "Zahlungstransaktionen"
+  "payment_gateways.transactions.title": "Zahlungstransaktionen",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Bereinigung der Ansprüche planen",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Bereinigung der Ansprüche wird geplant…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Registrieren Sie den täglichen Bereinigungsplan, der abgeschlossene Zahlungssitzungsansprüche nach ihrem 24-stündigen Wiederholungsfenster entfernt.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Die Bereinigung der Zahlungssitzungsansprüche ist geplant."
 }

package/src/modules/payment_gateways/i18n/en.json

@@ -2,6 +2,9 @@
   "payment_gateways.captureMethod.automatic": "Automatic",
   "payment_gateways.captureMethod.manual": "Manual",
   "payment_gateways.column.gatewayStatus": "Gateway status",
+  "payment_gateways.errors.sessionAmountMismatch": "Payment session amount {amount} does not match the amount due for order {orderId}",
+  "payment_gateways.errors.sessionCurrencyMismatch": "Payment session currency {currencyCode} does not match the currency of order {orderId}",
+  "payment_gateways.errors.sessionOrderNotFound": "Order {orderId} was not found in the current scope",
   "payment_gateways.feature.capture": "Capture authorized payments",
   "payment_gateways.feature.manage": "Manage payment sessions",
   "payment_gateways.feature.refund": "Refund captured payments",
@@ -76,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Payment captured",
   "payment_gateways.transactions.success.refreshStatus": "Transaction status refreshed",
   "payment_gateways.transactions.tableTitle": "Transactions",
-  "payment_gateways.transactions.title": "Payment Transactions"
+  "payment_gateways.transactions.title": "Payment Transactions",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Schedule claim cleanup",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Scheduling claim cleanup…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Register the daily cleanup schedule that removes completed payment-session claims after their 24-hour replay window.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Payment-session claim cleanup is scheduled."
 }

package/src/modules/payment_gateways/i18n/es.json

@@ -2,6 +2,9 @@
   "payment_gateways.captureMethod.automatic": "Automatica",
   "payment_gateways.captureMethod.manual": "Manual",
   "payment_gateways.column.gatewayStatus": "Estado de la pasarela",
+  "payment_gateways.errors.sessionAmountMismatch": "El importe de la sesión de pago {amount} no coincide con el importe pendiente del pedido {orderId}",
+  "payment_gateways.errors.sessionCurrencyMismatch": "La moneda de la sesión de pago {currencyCode} no coincide con la moneda del pedido {orderId}",
+  "payment_gateways.errors.sessionOrderNotFound": "No se encontró el pedido {orderId} en el ámbito actual",
   "payment_gateways.feature.capture": "Capturar pagos autorizados",
   "payment_gateways.feature.manage": "Gestionar sesiones de pago",
   "payment_gateways.feature.refund": "Reembolsar pagos capturados",
@@ -76,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Pago capturado",
   "payment_gateways.transactions.success.refreshStatus": "El estado de la transaccion se actualizo",
   "payment_gateways.transactions.tableTitle": "Transacciones",
-  "payment_gateways.transactions.title": "Transacciones de pago"
+  "payment_gateways.transactions.title": "Transacciones de pago",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Programar limpieza de reclamaciones",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Programando limpieza de reclamaciones…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Registra la limpieza diaria que elimina las reclamaciones de sesiones de pago completadas después de su ventana de repetición de 24 horas.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "La limpieza de reclamaciones de sesiones de pago está programada."
 }

package/src/modules/payment_gateways/i18n/ko.json

@@ -0,0 +1,87 @@
+{
+  "payment_gateways.captureMethod.automatic": "자동",
+  "payment_gateways.captureMethod.manual": "수동",
+  "payment_gateways.column.gatewayStatus": "게이트웨이 상태",
+  "payment_gateways.errors.sessionAmountMismatch": "결제 세션 금액 {amount}가 주문 {orderId}에 대한 금액과 일치하지 않습니다.",
+  "payment_gateways.errors.sessionCurrencyMismatch": "결제 세션 통화 {currencyCode}가 주문 통화 {orderId}와 일치하지 않습니다.",
+  "payment_gateways.errors.sessionOrderNotFound": "현재 범위에서 {orderId} 주문을 찾을 수 없습니다.",
+  "payment_gateways.feature.capture": "승인된 결제 청구",
+  "payment_gateways.feature.manage": "결제 세션 관리",
+  "payment_gateways.feature.refund": "청구된 결제 환불",
+  "payment_gateways.feature.view": "결제 게이트웨이 트랜잭션 보기",
+  "payment_gateways.field.captureMethod": "게이트웨이 청구 방식",
+  "payment_gateways.field.paymentTypes": "게이트웨이 결제 유형",
+  "payment_gateways.nav.transactions": "결제 트랜잭션",
+  "payment_gateways.status.authorized": "승인됨",
+  "payment_gateways.status.cancelled": "취소됨",
+  "payment_gateways.status.captured": "청구됨",
+  "payment_gateways.status.expired": "만료됨",
+  "payment_gateways.status.failed": "실패",
+  "payment_gateways.status.partially_captured": "부분 청구됨",
+  "payment_gateways.status.partially_refunded": "부분 환불됨",
+  "payment_gateways.status.pending": "대기 중",
+  "payment_gateways.status.refunded": "환불됨",
+  "payment_gateways.status.unknown": "알 수 없음",
+  "payment_gateways.transactions.actions.capture": "결제 청구",
+  "payment_gateways.transactions.actions.hideDetails": "상세 정보 숨기기",
+  "payment_gateways.transactions.actions.refreshStatus": "상태 새로고침",
+  "payment_gateways.transactions.actions.showDetails": "상세 정보 표시",
+  "payment_gateways.transactions.columns.amount": "금액",
+  "payment_gateways.transactions.columns.createdAt": "생성일",
+  "payment_gateways.transactions.columns.eventType": "이벤트 유형",
+  "payment_gateways.transactions.columns.gatewayPaymentId": "게이트웨이 결제 ID",
+  "payment_gateways.transactions.columns.gatewayRefundId": "게이트웨이 환불 ID",
+  "payment_gateways.transactions.columns.lastPolledAt": "마지막 폴링",
+  "payment_gateways.transactions.columns.lastWebhookAt": "마지막 웹훅",
+  "payment_gateways.transactions.columns.level": "레벨",
+  "payment_gateways.transactions.columns.message": "메시지",
+  "payment_gateways.transactions.columns.paymentId": "결제 ID",
+  "payment_gateways.transactions.columns.processed": "처리됨",
+  "payment_gateways.transactions.columns.provider": "제공업체",
+  "payment_gateways.transactions.columns.receivedAt": "수신일",
+  "payment_gateways.transactions.columns.redirectUrl": "리디렉션 URL",
+  "payment_gateways.transactions.columns.session": "세션 ID",
+  "payment_gateways.transactions.columns.status": "상태",
+  "payment_gateways.transactions.columns.time": "시간",
+  "payment_gateways.transactions.columns.transactionId": "트랜잭션 ID",
+  "payment_gateways.transactions.columns.updatedAt": "수정일",
+  "payment_gateways.transactions.description": "모든 결제 게이트웨이 트랜잭션을 추적하고, 웹훅 활동을 확인하며, 제공업체 로그를 한 곳에서 검토하세요.",
+  "payment_gateways.transactions.detail.gatewayMetadata": "게이트웨이 메타데이터",
+  "payment_gateways.transactions.detail.identifiers": "식별자",
+  "payment_gateways.transactions.detail.loading": "트랜잭션 상세 정보를 불러오는 중",
+  "payment_gateways.transactions.detail.logs": "게이트웨이 로그",
+  "payment_gateways.transactions.detail.logsEmpty": "이 트랜잭션에 대한 로그가 아직 없습니다.",
+  "payment_gateways.transactions.detail.summary.amount": "금액",
+  "payment_gateways.transactions.detail.summary.gatewayStatus": "게이트웨이 상태",
+  "payment_gateways.transactions.detail.summary.provider": "제공업체",
+  "payment_gateways.transactions.detail.summary.status": "상태",
+  "payment_gateways.transactions.detail.title": "트랜잭션 상세 정보",
+  "payment_gateways.transactions.detail.webhooks": "웹훅 활동",
+  "payment_gateways.transactions.detail.webhooksEmpty": "이 트랜잭션에 대해 기록된 웹훅 이벤트가 아직 없습니다.",
+  "payment_gateways.transactions.error.capture": "결제 청구에 실패했습니다",
+  "payment_gateways.transactions.error.load": "결제 트랜잭션을 불러오지 못했습니다",
+  "payment_gateways.transactions.error.loadDetail": "트랜잭션 상세 정보를 불러오지 못했습니다",
+  "payment_gateways.transactions.error.refreshStatus": "트랜잭션 상태를 새로고침하지 못했습니다",
+  "payment_gateways.transactions.filters.allProviders": "모든 제공업체",
+  "payment_gateways.transactions.filters.allStatuses": "모든 상태",
+  "payment_gateways.transactions.filters.provider": "제공업체",
+  "payment_gateways.transactions.filters.status": "상태",
+  "payment_gateways.transactions.level.error": "오류",
+  "payment_gateways.transactions.level.info": "정보",
+  "payment_gateways.transactions.level.warn": "경고",
+  "payment_gateways.transactions.log.code": "코드",
+  "payment_gateways.transactions.log.entityId": "엔터티 ID",
+  "payment_gateways.transactions.log.entityType": "엔터티 유형",
+  "payment_gateways.transactions.log.level": "레벨",
+  "payment_gateways.transactions.log.runId": "실행 ID",
+  "payment_gateways.transactions.log.time": "시간",
+  "payment_gateways.transactions.searchPlaceholder": "결제, 트랜잭션, 세션 또는 게이트웨이 ID로 검색",
+  "payment_gateways.transactions.success.capture": "결제가 청구되었습니다",
+  "payment_gateways.transactions.success.refreshStatus": "트랜잭션 상태가 새로고침되었습니다",
+  "payment_gateways.transactions.tableTitle": "트랜잭션",
+  "payment_gateways.transactions.title": "결제 트랜잭션",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "소유권 주장 정리 예약",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "소유권 주장 정리 예약 중…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "24시간 재생 창 이후 완료된 지불 세션 청구를 제거하는 일일 정리 일정을 등록하십시오.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "결제 세션 청구 정리가 예정되어 있습니다."
+}

package/src/modules/payment_gateways/i18n/pl.json

@@ -2,6 +2,9 @@
   "payment_gateways.captureMethod.automatic": "Automatyczny",
   "payment_gateways.captureMethod.manual": "Manualny",
   "payment_gateways.column.gatewayStatus": "Status bramki",
+  "payment_gateways.errors.sessionAmountMismatch": "Kwota sesji płatności {amount} nie zgadza się z kwotą do zapłaty dla zamówienia {orderId}",
+  "payment_gateways.errors.sessionCurrencyMismatch": "Waluta sesji płatności {currencyCode} nie zgadza się z walutą zamówienia {orderId}",
+  "payment_gateways.errors.sessionOrderNotFound": "Nie znaleziono zamówienia {orderId} w bieżącym zakresie",
   "payment_gateways.feature.capture": "Przechwytywanie autoryzowanych płatności",
   "payment_gateways.feature.manage": "Zarządzanie sesjami płatności",
   "payment_gateways.feature.refund": "Zwroty przechwyconych płatności",
@@ -76,5 +79,9 @@
   "payment_gateways.transactions.success.capture": "Płatność została przechwycona",
   "payment_gateways.transactions.success.refreshStatus": "Status transakcji odświeżony",
   "payment_gateways.transactions.tableTitle": "Transakcje",
-  "payment_gateways.transactions.title": "Transakcje płatności"
+  "payment_gateways.transactions.title": "Transakcje płatności",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.cta": "Zaplanuj czyszczenie roszczeń",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.loading": "Planowanie czyszczenia roszczeń…",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.message": "Zarejestruj codzienny harmonogram usuwający zakończone roszczenia inicjalizacji sesji płatności po 24-godzinnym oknie ponowienia.",
+  "payment_gateways.upgradeActions.sessionInitializationPrune.success": "Czyszczenie roszczeń inicjalizacji sesji płatności zostało zaplanowane."
 }

package/src/modules/payment_gateways/lib/capture-ledger.ts

@@ -0,0 +1,260 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { UnifiedPaymentStatus } from '@open-mercato/shared/modules/payment_gateways/types'
+import { GatewayPaymentOperation, GatewayTransaction } from '../data/entities'
+
+type Scope = { organizationId: string; tenantId: string }
+
+const AMOUNT_SCALE = 4
+const AMOUNT_UNITS_PER_WHOLE = 10n ** BigInt(AMOUNT_SCALE)
+const DECIMAL_PATTERN = /^(-?)(\d*)(?:\.(\d*))?$/
+
+/**
+ * Money in this module lives in `numeric(18,4)` columns and is read back as strings. Every
+ * comparison and every sum runs on integer minor units (1 unit = 10^-4) so partial captures
+ * never accumulate floating-point drift. Extra precision beyond four decimals is rounded
+ * half-up, matching what Postgres would store in the column anyway.
+ */
+export function parseAmountUnits(value: string | number | null | undefined): bigint {
+  if (value === null || value === undefined) 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
+}
+
+export function formatAmountUnits(units: bigint): string {
+  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: bigint): string {
+  return formatAmountUnits(units).replace(/\.?0+$/, '')
+}
+
+function captureConflict(code: string, message: string): CrudHttpError {
+  return new CrudHttpError(409, { error: message, code })
+}
+
+export type CaptureAmounts = {
+  authorizedUnits: bigint
+  capturedUnits: bigint
+  remainingUnits: bigint
+  requestedUnits: bigint
+}
+
+/**
+ * Resolves what a capture request means for the transaction's running total. An omitted
+ * amount captures everything that is still authorized, not the original full amount.
+ */
+export function resolveCaptureAmounts(transaction: GatewayTransaction, amount: number | undefined): CaptureAmounts {
+  const authorizedUnits = parseAmountUnits(transaction.amount)
+  const capturedUnits = parseAmountUnits(transaction.capturedAmount)
+  const remainingUnits = authorizedUnits - capturedUnits
+  return {
+    authorizedUnits,
+    capturedUnits,
+    remainingUnits,
+    requestedUnits: amount === undefined ? remainingUnits : parseAmountUnits(amount),
+  }
+}
+
+/**
+ * Rejects a capture whose amount would push the captured-to-date total past the authorized
+ * amount. This is the cumulative ceiling: each individual request may look small, but the
+ * sum of all captures against one authorization can never exceed it (#4487).
+ */
+export function assertCaptureWithinRemaining(
+  transaction: GatewayTransaction,
+  amount: number | undefined,
+): CaptureAmounts {
+  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
+}
+
+/**
+ * Claims the requested slice of the authorized amount before the provider is called, so two
+ * concurrent captures can never both charge. The increment is a compare-and-swap on the
+ * previous captured-to-date value: whoever loses it never reaches the adapter. The reserved
+ * amount is stamped on the operation row in the same transaction, so a retry of the same
+ * operation id reuses its reservation instead of reserving twice.
+ */
+export async function reserveCaptureAmount(em: EntityManager, input: {
+  transaction: GatewayTransaction
+  operation: GatewayPaymentOperation
+  amount: number | undefined
+  scope: Scope
+}): Promise<bigint> {
+  if (input.operation.reservedAmount !== null && input.operation.reservedAmount !== undefined) {
+    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: 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: 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
+}
+
+/**
+ * Reconciles the reservation with what the provider actually captured. Runs on the transaction
+ * instance loaded inside the completion transaction, so the adjustment commits together with
+ * the operation result.
+ */
+export function settleCapturedAmount(
+  transaction: GatewayTransaction,
+  reservedUnits: bigint,
+  capturedAmount: number | undefined,
+): void {
+  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)
+}
+
+/**
+ * Keeps the ledger honest for captures that happened outside the capture endpoint. A webhook or a
+ * status poll reports money that already moved but carries no captured amount, so only `captured`
+ * — the provider saying the whole authorization was taken — can be translated into a number: the
+ * full amount. The ledger is raised, never lowered, so an already recorded capture survives.
+ * `partially_captured` carries no recoverable amount, so it is left alone and the remainder stays
+ * capturable.
+ */
+export function alignCapturedAmountWithStatus(
+  transaction: GatewayTransaction,
+  status: UnifiedPaymentStatus,
+): void {
+  if (status !== 'captured') return
+  const authorizedUnits = parseAmountUnits(transaction.amount)
+  if (parseAmountUnits(transaction.capturedAmount) >= authorizedUnits) return
+  transaction.capturedAmount = formatAmountUnits(authorizedUnits)
+}
+
+/**
+ * Gives the reserved slice back after a failed provider call. Both writes share one
+ * transaction, so a partial release is impossible: either the amount becomes capturable again
+ * and the operation stops holding it, or the reservation stays outstanding. Returning `false`
+ * means the reservation is still held — the conservative outcome when it is unknown whether
+ * the provider took the money.
+ */
+export async function releaseCaptureAmount(em: EntityManager, input: {
+  transactionId: string
+  operation: GatewayPaymentOperation
+  reservedUnits: bigint
+  scope: Scope
+}): Promise<boolean> {
+  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,
+        },
+        undefined,
+        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: 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: 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
+  }
+}