LedgerRefundTarget — @gj-kit/toss-payments

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

Verified import example

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

Signature, parameters, and return type

/**
 * The app-owned reconciliation target for {@link compareLedgerRefund}.
 *
 * The library never derives or stores this number — how much *should* have been refunded is
 * ledger state the consuming app owns, validates and persists. The helper only answers
 * whether the provider snapshot confirms it.
 */
interface LedgerRefundTarget {
    /**
     * Cumulative amount the app's ledger expects the provider to have refunded for this
     * payment. Must be a non-negative safe integer; anything else yields
     * `kind: 'mismatch'` with `invalidLedgerTarget: true` instead of a guessed verdict.
     */
    readonly expectedRefundedAmount: number;
    /**
     * Optional: the amount of the *single refund request currently being reconciled* —
     * i.e. `expectedRefundedAmount` = previously-confirmed refunds + `requestedAmount`.
     *
     * When provided, a `'mismatch'` / `'provider-below-ledger'` verdict carries
     * {@link LedgerRefundShortfall} in `shortfall`, distinguishing `'at-prior-state'` (the
     * provider sits exactly at the pre-request amount with nothing in flight — the request
     * most likely never reached the provider, so replaying a sealed idempotent cancel request
     * is the natural recovery) from `'unexplained'` (any other shortfall — hold for a human).
     * Without it the helper cannot tell those two apart. Must, when present, be a safe
     * integer with `0 <= requestedAmount <= expectedRefundedAmount`; anything else yields
     * `kind: 'mismatch'` with `invalidLedgerTarget: true`.
     */
    readonly requestedAmount?: number;
}

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