LedgerRefundTarget — @gj-kit/toss-payments

@gj-kit/toss-payments에서 공개하는 interface입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

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

시그니처, 매개변수, 반환 타입

/**
 * 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;
}

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

• 패키지: @gj-kit/toss-payments
• 버전: 0.6.1
• 공개 entry: .
• 소스: GitHub

구현 주석

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.