ConfirmFlowOptions — @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 { ConfirmFlowOptions } from '@gj-kit/toss-payments/server';

Signature, parameters, and return type

interface ConfirmFlowOptions {
    /**
     * 기본 10분(600_000ms). Phase 0 확정: 인증 완료(successUrl 리다이렉트) 후 10분,
     * 초과 시 상태 EXPIRED → confirm은 404 NOT_FOUND_PAYMENT_SESSION(재시도 불가 최종 실패).
     * 30분은 결제창 실행(READY)→구매자 인증 구간의 별개 시한 — 라이브러리 통제 밖.
     */
    /** 1~600_000ms의 안전한 정수. provider 승인 시한(10분)을 넘겨 local 검증을 느슨하게 할 수 없다. */
    readonly approvalWindowMs?: number;
    readonly clock?: () => Date;
    /**
     * §3.1 가상계좌 secret 자동 저장 — confirm/confirmCallback이 Ok이고
     * **`payment.method === '가상계좌'`일 때만** saveSecret을 await 호출한다.
     *
     * method 가드 근거(Phase 5 실측): BILLING 카드 결제 응답에도 secret이 non-null로
     * 내려온다 — secret 존재로 판정하면 빌링 결제마다 무의미한 저장이 발생한다.
     *
     * 저장 실패여도 confirm은 **Ok 유지**(협상 불가) — 승인은 토스 측에서 이미 완결이라
     * Err로 뒤집으면 "승인됐는데 실패 처리 + 사용자 재confirm"이라는 더 큰 사고가 된다.
     * 가상계좌 secret은 승인 응답에서만 얻을 수 있고 조회로 복구할 수 없으므로, 저장 실패는
     * 반드시 운영 알림·재처리 대상으로 남겨야 한다. 실패 통지:
     * {@link onDepositSecretSaveFailed} + 'deposit.secret-save-failed' 이벤트.
     */
    readonly depositSecrets?: DepositSecretStore;
    /**
     * saveSecret 실패 통지 — payload에 **secret 원문 미포함**(로그 유출 방지).
     * 가상계좌 secret은 조회로 복구할 수 없으므로, 호출자는 결제를 보류하고 승인 응답 원문을
     * 노출하지 않는 운영 복구 절차를 통해 처리해야 한다.
     * 미지정 시 실패 1건당 console.warn 1회(라이브러리에서 유일하게 시끄러운 기본값 —
     * 침묵 유실 방지: 저장 누락 = 해당 주문의 DEPOSIT_CALLBACK 전부 unknown-order 거부).
     * 이 콜백의 throw는 삼켜진다(Ok 확정 결과 무간섭).
     */
    readonly onDepositSecretSaveFailed?: (info: {
        readonly orderId: OrderId;
        readonly paymentKey: PaymentKey;
        readonly cause: unknown;
    }) => void;
    /**
     * §3.3 이벤트 버스 — 'payment.confirmed' / 'payment.confirm-failed' /
     * 'deposit.secret-saved' / 'deposit.secret-save-failed' 발행 지점.
     * createTossEvents 산출물만 발행이 흐른다(구조적 모조 객체는 no-op).
     */
    readonly events?: TossEvents;
}

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