@open-mercato/core 0.6.7-develop.6695.1.d1b48a09b3 → 0.6.7-develop.6706.1.b3a4c759bb

package/src/modules/customers/components/detail/CompanyKpiBar.tsx

@@ -11,6 +11,7 @@ import {
   writeVersionedIdSet,
   clearVersionedPreference,
 } from '@open-mercato/shared/lib/browser/versionedPreference'
+import { isOpenDealStatus, isWonDealStatus } from '../../lib/dealStatus'
 import type { CompanyOverview, DealSummary, InteractionSummary } from '../formConfig'
 import { formatCurrency } from './utils'
 
@@ -19,7 +20,7 @@ const STORAGE_VERSION = 1
 
 function sumActiveDeals(deals: DealSummary[]): number {
   return deals
-    .filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+    .filter((d) => isOpenDealStatus(d.status))
     .reduce((sum, d) => {
       const amount = typeof d.valueAmount === 'number' ? d.valueAmount : parseFloat(String(d.valueAmount ?? '0'))
       return sum + (Number.isFinite(amount) ? amount : 0)
@@ -27,7 +28,7 @@ function sumActiveDeals(deals: DealSummary[]): number {
 }
 
 function getActiveDeals(deals: DealSummary[]): DealSummary[] {
-  return deals.filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+  return deals.filter((d) => isOpenDealStatus(d.status))
 }
 
 function computeActivityTrend(interactions: InteractionSummary[]): KpiTrend | undefined {
@@ -51,7 +52,7 @@ function computeActivityTrend(interactions: InteractionSummary[]): KpiTrend | un
 }
 
 function computeDealTrend(deals: DealSummary[]): KpiTrend | undefined {
-  const active = deals.filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+  const active = deals.filter((d) => isOpenDealStatus(d.status))
   if (active.length === 0) return undefined
   const now = Date.now()
   const monthMs = 30 * 86_400_000
@@ -81,7 +82,7 @@ export function CompanyKpiBar({ data }: CompanyKpiBarProps) {
 
   const ltvValue = React.useMemo(() => {
     if (data.kpis?.ltvValue !== undefined) return data.kpis.ltvValue
-    const wonDeals = data.deals.filter((d) => d.status === 'won')
+    const wonDeals = data.deals.filter((d) => isWonDealStatus(d.status))
     if (wonDeals.length === 0) return null
     return wonDeals.reduce((sum, d) => {
       const amt = typeof d.valueAmount === 'number' ? d.valueAmount : parseFloat(String(d.valueAmount ?? '0'))
@@ -154,7 +155,7 @@ export function CompanyKpiBar({ data }: CompanyKpiBarProps) {
           : `${v} ${v === 1 ? t('customers.companies.dashboard.kpi.year', 'year') : t('customers.companies.dashboard.kpi.years', 'years')}`
         : undefined,
       comparisonLabel: clientTenureYears !== null
-        ? `${data.kpis?.completedDealsCount ?? data.deals.filter((d) => d.status === 'won').length} ${t('customers.companies.dashboard.kpi.completedDeals', 'completed deals')}`
+        ? `${data.kpis?.completedDealsCount ?? data.deals.filter((d) => isWonDealStatus(d.status)).length} ${t('customers.companies.dashboard.kpi.completedDeals', 'completed deals')}`
         : t('customers.companies.dashboard.kpi.noInteractions', 'No interactions yet'),
     },
   ], [t, activeDealsValue, dealTrend, dealCurrency, activeDeals.length, activityTrend, ltvValue, clientTenureYears, data.deals, data.interactions.length, data.kpis])

package/src/modules/customers/components/detail/dashboard/helpers.ts

@@ -1,9 +1,10 @@
 import type { KpiTrend } from '@open-mercato/ui/backend/charts/KpiCard'
+import { isOpenDealStatus } from '../../../lib/dealStatus'
 import type { DealSummary, InteractionSummary, TodoLinkSummary } from '../../formConfig'
 
 export function sumActiveDeals(deals: DealSummary[]): number {
   return deals
-    .filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+    .filter((d) => isOpenDealStatus(d.status))
     .reduce((sum, d) => {
       const amount = typeof d.valueAmount === 'number' ? d.valueAmount : parseFloat(String(d.valueAmount ?? '0'))
       return sum + (Number.isFinite(amount) ? amount : 0)
@@ -11,7 +12,7 @@ export function sumActiveDeals(deals: DealSummary[]): number {
 }
 
 export function getActiveDeals(deals: DealSummary[]): DealSummary[] {
-  return deals.filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+  return deals.filter((d) => isOpenDealStatus(d.status))
 }
 
 export function getOpenTasks(todos: TodoLinkSummary[]): TodoLinkSummary[] {
@@ -68,7 +69,7 @@ export function computeActivityTrend(interactions: InteractionSummary[]): KpiTre
 }
 
 export function computeDealTrend(deals: DealSummary[]): KpiTrend | undefined {
-  const active = deals.filter((d) => d.status !== 'won' && d.status !== 'lost' && d.status !== 'closed')
+  const active = deals.filter((d) => isOpenDealStatus(d.status))
   if (active.length === 0) return undefined
   const now = Date.now()
   const monthMs = 30 * 86_400_000

package/src/modules/customers/lib/dealStatus.ts

@@ -0,0 +1,48 @@
+// Single source of truth for deal open/closed (terminal) semantics.
+//
+// `customer_deals.status` is a lenient text column and the supported writers do not agree on
+// one spelling: the closure hooks and the kanban board persist `win` / `loose`, the AI tool
+// `customers.update_deal_stage` persists `won` / `lost`, and the seeded vocabulary also carries
+// `closed`. The terminal set below therefore covers every spelling a status writer persists, so
+// status-based readers can share one classification. `closureOutcome` is a separate signal and
+// callers that combine both columns must handle it explicitly.
+//
+// A status not known to code counts as OPEN. Deal stages are configurable per tenant, so the
+// lenient column can hold values this module has never seen — treating them as open keeps them
+// visible in active-deal counts instead of silently reclassifying them as closed.
+
+export const DEAL_STATUS_WIN = 'win' as const
+export const DEAL_STATUS_LOSE = 'loose' as const
+export const DEAL_STATUS_CLOSED = 'closed' as const
+
+// `won` / `lost` are the spellings the AI stage tool writes; `win` / `loose` are what the UI
+// closure flows persist. Both are accepted so neither writer produces an unreadable status.
+export const WON_DEAL_STATUS_LIST: readonly string[] = [DEAL_STATUS_WIN, 'won']
+
+export const LOST_DEAL_STATUS_LIST: readonly string[] = [DEAL_STATUS_LOSE, 'lost']
+
+export const CLOSED_DEAL_STATUS_LIST: readonly string[] = [
+  ...WON_DEAL_STATUS_LIST,
+  ...LOST_DEAL_STATUS_LIST,
+  DEAL_STATUS_CLOSED,
+]
+
+const WON_DEAL_STATUSES = new Set<string>(WON_DEAL_STATUS_LIST)
+const LOST_DEAL_STATUSES = new Set<string>(LOST_DEAL_STATUS_LIST)
+const CLOSED_DEAL_STATUSES = new Set<string>(CLOSED_DEAL_STATUS_LIST)
+
+export function isWonDealStatus(value: string | null | undefined): boolean {
+  return value != null && WON_DEAL_STATUSES.has(value)
+}
+
+export function isLostDealStatus(value: string | null | undefined): boolean {
+  return value != null && LOST_DEAL_STATUSES.has(value)
+}
+
+export function isClosedDealStatus(value: string | null | undefined): boolean {
+  return value != null && CLOSED_DEAL_STATUSES.has(value)
+}
+
+export function isOpenDealStatus(value: string | null | undefined): boolean {
+  return !isClosedDealStatus(value)
+}

package/src/modules/payment_gateways/api/sessions/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { createSessionSchema } from '../../data/validators'
 import type { PaymentGatewayService } from '../../lib/gateway-service'
 import { paymentGatewaysTag } from '../openapi'
@@ -98,6 +99,9 @@ export async function POST(req: Request) {
       paymentId: transaction.paymentId,
     }, { status: 201 })
   } catch (err: unknown) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
     const message = err instanceof Error ? err.message : 'Failed to create payment session'
     const status = message.includes('No gateway adapter') ? 422 : 502
     return NextResponse.json({ error: message }, { status })
@@ -113,6 +117,7 @@ export const openApi = {
       tags: [paymentGatewaysTag],
       responses: [
         { status: 201, description: 'Payment session created' },
+        { status: 409, description: 'Amount or currency does not match the referenced order' },
         { status: 422, description: 'Invalid payload or unknown provider' },
         { status: 502, description: 'Gateway provider error' },
       ],

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/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",

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",

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",

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",

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

@@ -11,6 +11,7 @@ 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'
@@ -21,6 +22,7 @@ import { GatewayPaymentOperation, GatewaySessionInitialization, GatewayTransacti
 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,
@@ -76,6 +78,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
@@ -405,6 +412,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 = {

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/sales/di.ts

@@ -8,6 +8,7 @@ import { DefaultSalesCalculationService } from './services/salesCalculationServi
 import { DefaultTaxCalculationService } from './services/taxCalculationService'
 import { SalesDocumentNumberGenerator } from './services/salesDocumentNumberGenerator'
 import { DefaultSalesOrderService } from './services/salesOrderService'
+import { createSalesPaymentOrderTotalResolver } from './services/paymentOrderTotalResolver'
 import {
   SalesOrder,
   SalesOrderLine,
@@ -150,6 +151,14 @@ export function register(container: AppContainer) {
     })
       .singleton()
       .proxy(),
+    // Authoritative amount-due lookup consumed by `payment_gateways` when it
+    // reconciles a caller-supplied payment-session amount (#4488). Registering
+    // it here keeps the gateway module free of any dependency on sales.
+    paymentOrderTotalResolver: asFunction(({ em }: AppCradle) => {
+      return createSalesPaymentOrderTotalResolver({ em })
+    })
+      .scoped()
+      .proxy(),
     SalesOrder: asValue(SalesOrder),
     SalesOrderLine: asValue(SalesOrderLine),
     SalesOrderAdjustment: asValue(SalesOrderAdjustment),

package/src/modules/sales/services/paymentOrderTotalResolver.ts

@@ -0,0 +1,67 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type {
+  PaymentGatewayScope,
+  PaymentOrderTotal,
+  PaymentOrderTotalResolver,
+} from '@open-mercato/shared/modules/payment_gateways/types'
+import { SalesOrder } from '../data/entities'
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+function toAmount(value: string | number | null | undefined): number {
+  const parsed = typeof value === 'number' ? value : Number(value ?? 0)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * The amount a gateway session may legitimately charge for an order: what is
+ * still due. `outstanding_amount` is recomputed from payments and refunds, so
+ * it is the authoritative value once either exists. Orders that were never
+ * paid fall back to the grand total, which also covers rows written before
+ * outstanding totals were tracked.
+ */
+export function resolveOrderAmountDue(order: Pick<
+  SalesOrder,
+  'outstandingAmount' | 'paidTotalAmount' | 'refundedTotalAmount' | 'grandTotalGrossAmount'
+>): number {
+  const outstanding = toAmount(order.outstandingAmount)
+  const paid = toAmount(order.paidTotalAmount)
+  const refunded = toAmount(order.refundedTotalAmount)
+  if (outstanding > 0 || paid > 0 || refunded > 0) return outstanding
+  return toAmount(order.grandTotalGrossAmount)
+}
+
+export function createSalesPaymentOrderTotalResolver(deps: { em: EntityManager }): PaymentOrderTotalResolver {
+  return {
+    async resolveOrderTotal(orderId: string, scope: PaymentGatewayScope): Promise<PaymentOrderTotal | null> {
+      if (!UUID_PATTERN.test(orderId) || !scope.tenantId || !scope.organizationId) return null
+      const order = await findOneWithDecryption(
+        deps.em,
+        SalesOrder,
+        {
+          id: orderId,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          deletedAt: null,
+        },
+        {
+          fields: [
+            'currencyCode',
+            'outstandingAmount',
+            'paidTotalAmount',
+            'refundedTotalAmount',
+            'grandTotalGrossAmount',
+          ] as const,
+        },
+        scope,
+      )
+      if (!order) return null
+      return {
+        orderId,
+        currencyCode: order.currencyCode,
+        amountDue: resolveOrderAmountDue(order),
+      }
+    },
+  }
+}