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

package/src/modules/payment_gateways/lib/gateway-service.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import {
   getGatewayAdapter,
   type CreateSessionInput,
@@ -11,16 +12,27 @@ import {
   type GatewayAdapter,
   type GatewayPaymentStatus,
   type PaymentGatewayPresentationRequest,
+  type PaymentOrderTotalResolver,
   type UnifiedPaymentStatus,
 } from '@open-mercato/shared/modules/payment_gateways/types'
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
 import type { IntegrationStateService } from '../../integrations/lib/state-service'
 import type { IntegrationLogService } from '../../integrations/lib/log-service'
-import { conflict } from '@open-mercato/shared/lib/crud/errors'
-import { GatewaySessionInitialization, GatewayTransaction } from '../data/entities'
+import { conflict, CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { GatewayPaymentOperation, GatewaySessionInitialization, GatewayTransaction } from '../data/entities'
 import { canApplyManualAction, isValidTransition, type ManualGatewayAction } from './status-machine'
 import { emitPaymentGatewayEvent } from '../events'
 import { readGatewayMetadata, readWebhookLog } from './transaction-fields'
+import { reconcileSessionAmountWithOrder } from './order-amount-reconciliation'
+import {
+  alignCapturedAmountWithStatus,
+  assertCaptureWithinRemaining,
+  formatAmountUnits,
+  parseAmountUnits,
+  releaseCaptureAmount,
+  reserveCaptureAmount,
+  settleCapturedAmount,
+} from './capture-ledger'
 import {
   completePaymentOperation,
   failPaymentOperation,
@@ -37,6 +49,7 @@ import {
 
 const PAYMENT_SESSION_CLAIM_STALE_MS = 30_000
 const PAYMENT_SESSION_WAIT_INTERVAL_MS = 25
+const logger = createLogger('payment_gateways').child({ component: 'gateway-service' })
 
 function assertManualActionAllowed(action: ManualGatewayAction, transaction: GatewayTransaction): void {
   const current = transaction.unifiedStatus as UnifiedPaymentStatus
@@ -45,12 +58,6 @@ function assertManualActionAllowed(action: ManualGatewayAction, transaction: Gat
   }
 }
 
-function assertCaptureAmountAllowed(amount: number | undefined, transaction: GatewayTransaction): void {
-  if (amount !== undefined && amount > Number(transaction.amount)) {
-    throw conflict(`Capture amount ${amount} exceeds authorized transaction amount ${transaction.amount}`)
-  }
-}
-
 function applyAdapterResultStatus(
   action: ManualGatewayAction,
   transaction: GatewayTransaction,
@@ -73,6 +80,11 @@ export interface PaymentGatewayServiceDeps {
   integrationCredentialsService: CredentialsService
   integrationStateService?: IntegrationStateService
   integrationLogService?: IntegrationLogService
+  /**
+   * Optional seam supplied by the module that owns orders (`sales` by default).
+   * When absent, session amounts cannot be reconciled and are accepted as-is.
+   */
+  paymentOrderTotalResolver?: PaymentOrderTotalResolver | null
   sessionClaimOptions?: {
     staleAfterMs?: number
     heartbeatIntervalMs?: number
@@ -179,11 +191,10 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       : undefined
     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) ?? {}
 
@@ -199,6 +210,12 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
     payload: Record<string, unknown>
     scope: { organizationId: string; tenantId: string }
     assertInitialAllowed?: (transaction: GatewayTransaction) => void
+    beforeInvoke?: (context: { transaction: GatewayTransaction; operation: GatewayPaymentOperation }) => Promise<void>
+    releaseOnFailure?: (context: {
+      transaction: GatewayTransaction
+      operation: GatewayPaymentOperation
+      providerInvoked: boolean
+    }) => Promise<void>
     invoke: (context: {
       adapter: GatewayAdapter
       credentials: Record<string, unknown>
@@ -231,7 +248,17 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       return prepared.result as unknown as TResult
     }
 
+    const operation = prepared.claim.record
+    // Everything after this flips to true is post-settlement: the provider moved the money and the
+    // completion transaction committed it. A later event or logging failure must not undo either,
+    // so the failure path below only runs while the operation can still be rolled back.
+    let settled = false
+    // Flips once the provider call returned, so the failure path can tell "the provider never
+    // moved the money" from "the provider moved it and only our bookkeeping failed" — the two
+    // cases need opposite rollback decisions.
+    let providerInvoked = false
     try {
+      await input.beforeInvoke?.({ transaction, operation })
       const { adapter, credentials } = await resolveAdapterAndCredentials(
         transaction.providerKey,
         { organizationId: transaction.organizationId, tenantId: transaction.tenantId },
@@ -242,6 +269,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         transaction,
         idempotencyKey: prepared.claim.providerIdempotencyKey,
       })
+      providerInvoked = true
       const statusChanged = await completePaymentOperation(
         em,
         prepared.claim,
@@ -253,6 +281,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
           return changed
         },
       )
+      settled = true
       if (statusChanged) {
         await emitStatusEvent(result.status, {
           transactionId: transaction.id,
@@ -265,7 +294,12 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       await input.afterCommit(transaction, result)
       return result
     } catch (error: unknown) {
-      await Promise.allSettled([failPaymentOperation(em, prepared.claim)])
+      if (!settled) {
+        if (input.releaseOnFailure) {
+          await input.releaseOnFailure({ transaction, operation, providerInvoked }).catch(() => undefined)
+        }
+        await Promise.allSettled([failPaymentOperation(em, prepared.claim)])
+      }
       throw error
     }
   }
@@ -285,6 +319,9 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         ?? (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 ?? {}),
@@ -376,6 +413,13 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
   return {
     async createPaymentSession(input: CreatePaymentSessionInput): Promise<{ transaction: GatewayTransaction; session: CreateSessionResult }> {
       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: CreateSessionInput = {
@@ -426,7 +470,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
             scope,
           )
           if (!transaction) {
-            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, session: restoreSession(transaction) }
         }
@@ -447,7 +491,15 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
         try {
           session = await adapter.createSession({ ...sessionInput, idempotencyKey: operationKey })
         } catch (error) {
-          await releasePaymentSessionInitialization(em, ownership, scope).catch(() => undefined)
+          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()
@@ -491,16 +543,57 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       scope: { organizationId: string; tenantId: string },
       operationId?: string,
     ): Promise<CaptureResult> {
+      let reservedUnits: bigint | null = 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 })
+          // "Capture the rest" has to name the remaining amount once part of the authorization is
+          // already captured, otherwise the provider would capture the full amount a second time.
+          if (amount === undefined && 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,
         }),
@@ -509,6 +602,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
             ...readGatewayMetadata(transaction.gatewayMetadata),
             captureResult: result.providerData,
           }
+          if (reservedUnits !== null) settleCapturedAmount(transaction, reservedUnits, result.capturedAmount)
         },
         afterCommit: (transaction, result) => writeTransactionLog(
           transaction.providerKey,
@@ -604,6 +698,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       if (status.status !== transaction.unifiedStatus && isValidTransition(transaction.unifiedStatus as UnifiedPaymentStatus, 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 = new Date()
@@ -650,6 +745,7 @@ export function createPaymentGatewayService(deps: PaymentGatewayServiceDeps) {
       const previousStatus = transaction.unifiedStatus
       if (shouldApplyStatus) {
         transaction.unifiedStatus = update.unifiedStatus
+        alignCapturedAmountWithStatus(transaction, update.unifiedStatus)
       }
       if (update.providerStatus) {
         transaction.gatewayStatus = update.providerStatus

package/src/modules/payment_gateways/lib/order-amount-reconciliation.ts

@@ -0,0 +1,93 @@
+import { conflict } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createFallbackTranslator, type TranslateWithFallbackFn } from '@open-mercato/shared/lib/i18n/translate'
+import type {
+  PaymentGatewayScope,
+  PaymentOrderTotal,
+  PaymentOrderTotalResolver,
+} from '@open-mercato/shared/modules/payment_gateways/types'
+
+/** Amounts are stored as numeric(18,4); anything below that is rounding noise, not a mismatch. */
+const AMOUNT_TOLERANCE = 0.0001
+
+function normalizeCurrencyCode(currencyCode: string): string {
+  return currencyCode.trim().toUpperCase()
+}
+
+/**
+ * Conflict copy is served from the module catalog on a request path. Contexts
+ * without a registered module dictionary (CLI commands, workers, unit tests)
+ * fall back to the English template shipped with each call, so a missing
+ * dictionary degrades the wording of a rejection but never its outcome.
+ */
+async function resolveConflictTranslator(): Promise<TranslateWithFallbackFn> {
+  try {
+    const { translate } = await resolveTranslations()
+    return translate
+  } catch {
+    return createFallbackTranslator({})
+  }
+}
+
+export function isPaymentOrderTotalResolver(candidate: unknown): candidate is PaymentOrderTotalResolver {
+  return !!candidate
+    && typeof candidate === 'object'
+    && typeof (candidate as PaymentOrderTotalResolver).resolveOrderTotal === 'function'
+}
+
+export function assertSessionAmountMatchesOrderTotal(
+  requested: { orderId: string; amount: number; currencyCode: string },
+  orderTotal: PaymentOrderTotal,
+  translate: TranslateWithFallbackFn,
+): void {
+  if (normalizeCurrencyCode(requested.currencyCode) !== normalizeCurrencyCode(orderTotal.currencyCode)) {
+    throw conflict(translate(
+      'payment_gateways.errors.sessionCurrencyMismatch',
+      'Payment session currency {currencyCode} does not match the currency of order {orderId}',
+      { currencyCode: normalizeCurrencyCode(requested.currencyCode), orderId: requested.orderId },
+    ))
+  }
+  if (Math.abs(requested.amount - orderTotal.amountDue) > AMOUNT_TOLERANCE) {
+    throw conflict(translate(
+      'payment_gateways.errors.sessionAmountMismatch',
+      'Payment session amount {amount} does not match the amount due for order {orderId}',
+      { amount: requested.amount, orderId: requested.orderId },
+    ))
+  }
+}
+
+/**
+ * Reconciles a caller-supplied session amount against the authoritative amount
+ * due for the referenced order. Reconciliation is skipped when the request
+ * references no order, or when no module registered a resolver (for example an
+ * installation without the `sales` module) — there is nothing authoritative to
+ * compare against in either case. A referenced order that does not resolve
+ * inside the caller's tenant/organization scope is rejected exactly like an
+ * unknown one, so the response never reveals whether it exists elsewhere.
+ */
+export async function reconcileSessionAmountWithOrder(input: {
+  orderId?: string
+  amount: number
+  currencyCode: string
+  scope: PaymentGatewayScope
+  resolver?: PaymentOrderTotalResolver | null
+}): Promise<void> {
+  const { orderId, resolver } = input
+  if (!orderId || !resolver) return
+
+  const orderTotal = await resolver.resolveOrderTotal(orderId, input.scope)
+  const translate = await resolveConflictTranslator()
+  if (!orderTotal) {
+    throw conflict(translate(
+      'payment_gateways.errors.sessionOrderNotFound',
+      'Order {orderId} was not found in the current scope',
+      { orderId },
+    ))
+  }
+
+  assertSessionAmountMatchesOrderTotal(
+    { orderId, amount: input.amount, currencyCode: input.currencyCode },
+    orderTotal,
+    translate,
+  )
+}

package/src/modules/payment_gateways/lib/payment-operation-idempotency.ts

@@ -170,6 +170,7 @@ export async function preparePaymentOperation(
     attemptToken: claim.attemptToken,
     attemptCount: 1,
     result: null,
+    reservedAmount: null,
     leaseExpiresAt: claim.leaseExpiresAt,
     organizationId: input.scope.organizationId,
     tenantId: input.scope.tenantId,

package/src/modules/payment_gateways/lib/session-idempotency.ts

@@ -6,6 +6,11 @@ import { GatewaySessionInitialization } from '../data/entities'
 
 type Scope = { organizationId: string; tenantId: string }
 
+export const PAYMENT_SESSION_REPLAY_WINDOW_MS = 24 * 60 * 60 * 1000
+export const PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE =
+  'payment-gateway-session-initialization-prune'
+export const PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE = 1_000
+
 export type OwnedPaymentSessionInitialization = {
   id: string
   claimToken: string
@@ -140,3 +145,34 @@ export async function refreshPaymentSessionInitialization(
   )
   return refreshedRows > 0
 }
+
+export async function pruneCompletedPaymentSessionInitializations(
+  em: EntityManager,
+  scope: Scope,
+  options: { now?: Date; batchSize?: number } = {},
+): Promise<number> {
+  const now = options.now ?? new Date()
+  const batchSize = options.batchSize ?? PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    throw new Error('[internal] Payment-session initialization prune batch size must be a positive integer')
+  }
+  const cutoff = new Date(now.getTime() - PAYMENT_SESSION_REPLAY_WINDOW_MS)
+  const connection = em.getConnection()
+  const result = await connection.execute(
+    `
+    delete from gateway_session_initializations
+    where id in (
+      select id from gateway_session_initializations
+      where tenant_id = ?
+        and organization_id = ?
+        and gateway_transaction_id is not null
+        and updated_at < ?
+      order by updated_at asc
+      limit ?
+    )
+    `,
+    [scope.tenantId, scope.organizationId, cutoff, batchSize],
+    'run',
+  ) as { affectedRows?: number; rowCount?: number } | undefined
+  return result?.affectedRows ?? result?.rowCount ?? 0
+}

package/src/modules/payment_gateways/migrations/.snapshot-open-mercato.json

@@ -195,6 +195,23 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "reserved_amount": {
+          "name": "reserved_amount",
+          "type": "numeric(18,4)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": 18,
+          "scale": 4,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "decimal"
+        },
         "result": {
           "name": "result",
           "type": "jsonb",
@@ -520,6 +537,15 @@
           "primary": true,
           "unique": true
         },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "gateway_session_initializations_prune_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"gateway_session_initializations_prune_idx\" on \"gateway_session_initializations\" (\"tenant_id\", \"organization_id\", \"updated_at\") where \"gateway_transaction_id\" is not null"
+        },
         {
           "columnNames": [
             "operation_key",
@@ -560,6 +586,23 @@
           "enumItems": [],
           "mappedType": "decimal"
         },
+        "captured_amount": {
+          "name": "captured_amount",
+          "type": "numeric(18,4)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": 18,
+          "scale": 4,
+          "default": "'0'",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "decimal"
+        },
         "client_secret": {
           "name": "client_secret",
           "type": "text",
@@ -1128,4 +1171,4 @@
   ],
   "views": [],
   "nativeEnums": {}
-}
+}

package/src/modules/payment_gateways/migrations/Migration20260725101500_payment_gateways.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260725101500_payment_gateways extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "gateway_transactions" add column "captured_amount" numeric(18,4) not null default '0';`);
+    this.addSql(`alter table "gateway_payment_operations" add column "reserved_amount" numeric(18,4) null;`);
+    // Backfill the captured-to-date ledger from the succeeded capture operations, which are the
+    // only capture path since the payment operation ledger landed. Transactions captured before
+    // that (no succeeded capture rows) fall back to their full amount when their status says the
+    // money was taken. A historical `partially_captured` transaction has no recoverable captured
+    // amount, so it starts at 0 and can still be over-captured once.
+    this.addSql(`update "gateway_transactions" as t set "captured_amount" = coalesce((select sum((o."result"->>'capturedAmount')::numeric) from "gateway_payment_operations" as o where o."transaction_id" = t."id" and o."operation_type" = 'capture' and o."status" = 'succeeded'), case when t."unified_status" in ('captured', 'refunded', 'partially_refunded') then t."amount" else 0 end);`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "gateway_payment_operations" drop column "reserved_amount";`);
+    this.addSql(`alter table "gateway_transactions" drop column "captured_amount";`);
+  }
+
+}

package/src/modules/payment_gateways/migrations/Migration20260803103035_payment_gateways.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260803103035_payment_gateways extends Migration {
+  override isTransactional(): boolean {
+    return false
+  }
+
+  override up(): void | Promise<void> {
+    this.addSql(
+      'create index concurrently if not exists "gateway_session_initializations_prune_idx" on "gateway_session_initializations" ("tenant_id", "organization_id", "updated_at") where "gateway_transaction_id" is not null;',
+    )
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql('drop index concurrently if exists "gateway_session_initializations_prune_idx";')
+  }
+}

package/src/modules/payment_gateways/setup.ts

@@ -1,4 +1,62 @@
+import { createHash } from 'node:crypto'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE } from './lib/session-idempotency'
+
+type SchedulerServiceLike = {
+  register: (registration: Record<string, unknown>) => Promise<void>
+}
+
+const logger = createLogger('payment_gateways')
+
+function stableScheduleUuid(stableKey: string): string {
+  const hex = createHash('sha256').update(stableKey).digest('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+export async function registerSessionInitializationPruneSchedule(
+  container: import('awilix').AwilixContainer | undefined,
+  scope: { tenantId: string; organizationId: string },
+): Promise<boolean> {
+  if (!container) return false
+  const cradle = container as { hasRegistration?: (name: string) => boolean }
+  if (typeof cradle.hasRegistration !== 'function' || !cradle.hasRegistration('schedulerService')) {
+    return false
+  }
+
+  const schedulerService = container.resolve('schedulerService') as SchedulerServiceLike
+  await schedulerService.register({
+    id: stableScheduleUuid(
+      `payment_gateways:session-initialization-prune:${scope.tenantId}:${scope.organizationId}`,
+    ),
+    name: 'Payment-session initialization prune',
+    description: 'Delete completed payment-session initialization claims after the 24-hour replay window.',
+    scopeType: 'organization',
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    scheduleType: 'interval',
+    scheduleValue: '24h',
+    timezone: 'UTC',
+    targetType: 'queue',
+    targetQueue: PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE,
+    targetPayload: scope,
+    sourceType: 'module',
+    sourceModule: 'payment_gateways',
+    isEnabled: true,
+  })
+  return true
+}
+
+async function ensureSessionInitializationPruneSchedule(
+  container: import('awilix').AwilixContainer | undefined,
+  scope: { tenantId: string; organizationId: string },
+): Promise<void> {
+  try {
+    await registerSessionInitializationPruneSchedule(container, scope)
+  } catch (error) {
+    logger.warn('Failed to register payment-session initialization prune schedule', { err: error })
+  }
+}
 
 export const setup: ModuleSetupConfig = {
   defaultRoleFeatures: {
@@ -6,6 +64,10 @@ export const setup: ModuleSetupConfig = {
     admin: ['payment_gateways.*'],
     employee: ['payment_gateways.view'],
   },
+
+  async seedDefaults({ container, tenantId, organizationId }) {
+    await ensureSessionInitializationPruneSchedule(container, { tenantId, organizationId })
+  },
 }
 
 export default setup

package/src/modules/payment_gateways/workers/session-initialization-prune.ts

@@ -0,0 +1,63 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createModuleQueue, type JobContext, type Queue, type QueuedJob, type WorkerMeta } from '@open-mercato/queue'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE,
+  PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE,
+  pruneCompletedPaymentSessionInitializations,
+} from '../lib/session-idempotency'
+
+type PrunePayload = {
+  tenantId?: string
+  organizationId?: string
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+const logger = createLogger('payment_gateways')
+let continuationQueue: Queue<PrunePayload> | null = null
+
+function getContinuationQueue(): Queue<PrunePayload> {
+  continuationQueue ??= createModuleQueue<PrunePayload>(
+    PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE,
+    { concurrency: 1 },
+  )
+  return continuationQueue
+}
+
+export const metadata: WorkerMeta = {
+  queue: PAYMENT_SESSION_INITIALIZATION_PRUNE_QUEUE,
+  id: 'payment_gateways:session-initialization-prune',
+  concurrency: 1,
+}
+
+export default async function handle(
+  job: QueuedJob<PrunePayload>,
+  ctx: HandlerContext,
+): Promise<void> {
+  const tenantId = job.payload?.tenantId
+  const organizationId = job.payload?.organizationId
+  if (!tenantId || !organizationId) {
+    logger.warn('Skipping payment-session initialization prune without tenant scope')
+    return
+  }
+
+  const em = ctx.resolve<EntityManager>('em').fork()
+  const deleted = await pruneCompletedPaymentSessionInitializations(
+    em,
+    { tenantId, organizationId },
+    { batchSize: PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE },
+  )
+  if (deleted > 0) {
+    logger.info('Pruned completed payment-session initialization claims', {
+      deleted,
+      tenantId,
+      organizationId,
+    })
+  }
+  if (deleted >= PAYMENT_SESSION_INITIALIZATION_PRUNE_BATCH_SIZE) {
+    await getContinuationQueue().enqueue({ tenantId, organizationId }, { delayMs: 1_000 })
+  }
+}