compareLedgerRefund — @gj-kit/toss-payments

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

Verified import example

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

Signature, parameters, and return type

/**
 * Compares a provider payment-state snapshot against the app ledger's cumulative refund
 * target — "has the provider confirmed the refunds my ledger claims?".
 *
 * Expressed purely in provider-snapshot terms: `snapshot.canceledAmount`
 * (`totalAmount - balanceAmount` at summarize time) is the provider's current cumulative
 * canceled amount, and `pendingCancelAmount` is the sum of `cancelAmount` over
 * `cancelStatus: 'IN_PROGRESS'` transactions. Per the kit's Phase-0 field measurements
 * (and the cancel path's own 2xx validation), an accepted async cancel already shows the
 * reduced balance while `IN_PROGRESS` — so pending amounts are *inside* `canceledAmount`,
 * and an aborted cancel takes the balance back up. `'settled'` therefore additionally
 * requires that nothing is in flight; see {@link LedgerRefundComparison} for the exact
 * three-way semantics. The ledger target stays app-owned — see {@link LedgerRefundTarget}.
 * Both the branded and the serialized snapshot forms are accepted; the ids play no part in
 * the verdict, so no re-branding is required. Comparing a snapshot of the *wrong payment*
 * against a ledger target is a caller-side identity error this helper cannot detect.
 *
 * Mapping to an app-side `SUCCEEDED / UNCONFIRMED / MISMATCH` three-way: `'settled'` maps
 * to succeeded, but the kit's `'unconfirmed'` is strictly the in-flight-cancel case — an
 * app-style "the cancel request likely never reached the provider, replay the sealed
 * request" state surfaces here as `'mismatch'` / `'provider-below-ledger'`. Pass
 * {@link LedgerRefundTarget.requestedAmount} to have that case labelled
 * `shortfall: 'at-prior-state'` (vs `'unexplained'`); do not map the three kit names 1:1
 * onto an app's replay policy without it.
 *
 * Honesty rule for broken inputs: when the snapshot's amounts are untrustworthy
 * (`invalid-amount`/`balance-exceeds-total` issues, or a `canceledAmount` that is not a
 * non-negative safe integer), the verdict is `'mismatch'` with
 * `direction: 'indeterminate'` and the gating issues attached. Deliberately *not*
 * reproduced: the "status CANCELED with only totalAmount valid ⇒ assume fully refunded"
 * fallback some reconciliation paths use — that is a guess, and settling a ledger on it
 * belongs to the app's explicit policy, not a library default.
 */
declare function compareLedgerRefund(snapshot: PaymentStateSnapshot | SerializedPaymentStateSnapshot, ledger: LedgerRefundTarget): LedgerRefundComparison;

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