import type { OrderRow, PaymentTransactionRow } from '../../../types/db/index.js'; /** * The reserved code of the built-in zero-checkout payment method. A cart * whose grand total is 0 accepts this method and nothing else. */ export declare const ZERO_CHECKOUT_CODE = "zero_checkout"; export type PaymentMethodInfo = { code: string; name: string; }; export interface PaymentMethodValidationContext { /** * The cart's `grand_total` in major currency units (already rounded by * `toPrice` when the cart computed it). Omit when no cart is in scope — * context-less callers keep the legacy behavior: zero-total-only methods * (`zero_checkout`) are hidden and every other method is unaffected. */ cartTotal?: number; } /** * What core hands a money operation. `order` is the full order row; `transaction` * is the `payment_transaction` the operation acts on — the authorization for * `capture`/`void`, the capture for `refund`. */ export interface PaymentOperationContext { order: OrderRow; transaction: PaymentTransactionRow; } /** * A `refund` also receives how much to refund. The handler returns the amount the * gateway ACTUALLY moved (its truth, not this request) — core decides full vs * partial from the cumulative confirmed total. */ export interface PaymentRefundContext extends PaymentOperationContext { /** Requested refund amount, in major currency units. */ amount: number; /** The order's currency (ISO code). */ currency: string; } /** * What a money-moving operation (`capture` / `refund`) reports back so core can * record the ledger entry, dedupe, and emit the lifecycle event. `void` returns * nothing — it moves no money and records no transaction. */ export interface PaymentOperationResult { /** The gateway's transaction id — recording key, idempotency, and event payload. */ transactionId: string; /** The amount actually moved, in major units (the gateway's confirmed figure). */ amount: number; /** Defaults to the order's currency. */ currency?: string; /** * Offline methods (COD, bank transfer): no gateway, nothing to reconcile. Core * records the transaction as offline and `transactionId` is a synthetic * reference. */ offline?: boolean; /** Raw gateway response, stored on the transaction's `additional_information`. */ raw?: unknown; } export type PaymentCaptureHandler = (context: PaymentOperationContext) => Promise; export type PaymentVoidHandler = (context: PaymentOperationContext) => Promise; export type PaymentRefundHandler = (context: PaymentRefundContext) => Promise; /** * The payment method registration contract. * * `init` + `validator` drive checkout availability (unchanged). The optional * operation handlers declare — by their **presence** — which post-order money * operations the method supports. Core owns the orchestration (admin action, * transaction recording, status transition, idempotency, and lifecycle event * emission) and calls a handler only for the gateway step; a handler that * returns `PaymentOperationResult` reports what the gateway did. * * A method omits any operation it doesn't support: an offline method (COD) * supplies trivial handlers that return `{ offline: true }`; a method with no * refund support omits `refund` and gets no refund action, by construction. * * Placing the order is the method's own step, not part of this contract: it * calls `markOrderPlaced` (oms services) when its payment succeeds, or when * the order is created for an offline method. That sets `placed_at` and emits * `order_placed`, once per order. */ export type PaymentMethodFactory = { /** Resolves the method's `{ code, name }`. */ init: () => PaymentMethodInfo | Promise; /** Checkout availability. Effectively required — see the registry validation below. */ validator?: (context?: PaymentMethodValidationContext) => boolean | Promise; /** Settle an authorized payment. Presence ⇒ the method supports capture. */ capture?: PaymentCaptureHandler; /** Release an uncaptured authorization. Presence ⇒ the method supports void. */ void?: PaymentVoidHandler; /** Return captured money, in full or part. Presence ⇒ the method supports refunds. */ refund?: PaymentRefundHandler; /** * Whether `refund` can return less than the full captured amount. Presence * can't express a boolean-of-a-capability, so this is an explicit flag; * defaults to `false`. */ supportsPartialRefund?: boolean; }; /** * This function retrieves the available payment methods from the registry. * @param context - Cart context forwarded to each factory's `validator`. * When `cartTotal` is 0 the list collapses to the zero-checkout method only. * @returns A promise that resolves to an array of payment methods. */ export declare function getAvailablePaymentMethods(context?: PaymentMethodValidationContext): Promise; /** * Registers a new payment method. * @param factory - The factory object that contains the init and optional validator methods. * @throws Will throw an error if the factory does not have an init method. */ export declare function registerPaymentMethod(factory: PaymentMethodFactory): void; /** * Resolve the registered factory for a payment method code — with its operation * handlers (`capture` / `void` / `refund`) — or `undefined` when none is * registered. Core operation services (`refundOrder`, and later capture/void) * use this to reach a method's gateway handlers; it matches by calling each * factory's `init()`. */ export declare function getPaymentMethodFactory(code: string): Promise;