LedgerRefundComparison — @gj-kit/toss-payments

A public type from @gj-kit/toss-payments/server. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

import { LedgerRefundComparison } from '@gj-kit/toss-payments/server';

Signature, parameters, and return type

/**
 * Verdict of {@link compareLedgerRefund} — a three-way discriminated union.
 *
 * Balance model (Phase-0 field measurements, enforced by the cancel path's response
 * validation): an accepted async cancel *already* reduces `balanceAmount` while its
 * `cancelStatus` is `IN_PROGRESS`; completion (`DONE`) keeps the reduction, abortion
 * (`ABORTED`) restores the balance. `snapshot.canceledAmount` therefore *includes*
 * in-flight amounts, and the final confirmed amount lies in
 * `[canceledAmount - pendingCancelAmount, canceledAmount]`.
 *
 * - `'settled'` — `snapshot.canceledAmount` equals the ledger target **and no cancel is in
 *   flight** (`pendingCancelAmount` is always `0` here). Only then is recording the refund
 *   as final safe: an `IN_PROGRESS` cancel could still resolve `ABORTED` and take the
 *   balance back up (money that never moved).
 * - `'unconfirmed'` — at least one `IN_PROGRESS` cancel keeps the verdict provisional, and
 *   the target lies within the possible final range above, so it may still settle without
 *   any new provider action. Do not settle the ledger yet; re-fetch the payment (a
 *   `CANCEL_STATUS_CHANGED` webhook is `unverified`) and compare again. This mirrors
 *   `lifecycle: 'cancellation-pending'` taking priority over amount-based `'full'`.
 * - `'mismatch'` — the target is outside every possible outcome (`direction` says which
 *   way; with `requestedAmount` supplied, `shortfall` splits `'provider-below-ledger'` into
 *   `'at-prior-state'` / `'unexplained'`), or the comparison is impossible
 *   (`direction: 'indeterminate'`): the snapshot's amounts carry consistency issues
 *   (attached in `consistencyIssues`), or the ledger target itself was invalid
 *   (`invalidLedgerTarget: true`).
 */
type LedgerRefundComparison = {
    readonly kind: "settled";
    /** Provider-confirmed cumulative canceled amount (`snapshot.canceledAmount`). */
    readonly canceledAmount: number;
    /** Always `0` in this verdict — any in-flight cancel forces `'unconfirmed'`. */
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
} | {
    readonly kind: "unconfirmed";
    readonly canceledAmount: number;
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
} | {
    readonly kind: "mismatch";
    readonly direction: LedgerRefundMismatchDirection;
    readonly canceledAmount: number;
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
    /**
     * `true` when `expectedRefundedAmount` (or a supplied `requestedAmount`) was not a
     * valid ledger amount.
     */
    readonly invalidLedgerTarget: boolean;
    /**
     * Present only when `direction: 'provider-below-ledger'` and the ledger supplied
     * `requestedAmount` — see {@link LedgerRefundShortfall}.
     */
    readonly shortfall?: LedgerRefundShortfall;
    /**
     * The amount-integrity issues that blocked the comparison (`invalid-amount`,
     * `balance-exceeds-total`) — empty for a plain amount mismatch. The snapshot keeps
     * the full issue list.
     */
    readonly consistencyIssues: readonly PaymentStateConsistencyIssue[];
};

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/toss-payments
• Version: 0.6.1
• Public entry: ./server
• Source: GitHub