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

Signature, parameters, and return type

interface TossEventMap {
    /**
     * 요청 라이프사이클 — started/succeeded/failed 3분할 대신 완료 1종(과설계 금지).
     * 논리 요청당 1회(최종 outcome). durationMs는 첫 시도 시작부터 최종 outcome 확정까지의
     * 총 경과(재시도 대기 포함) — 시도별 소요는 audit(§3.2)의 AuditEntry.durationMs로.
     */
    'api.call': {
        readonly method: string;
        readonly path: string;
        readonly outcome: 'ok' | 'toss-error' | 'transport';
        readonly httpStatus: number | null;
        readonly durationMs: number;
        readonly traceId: string | null;
        /** retry(§3.4) 결합 시 총 시도 수 — 미결합이면 1. */
        readonly attempts: number;
    };
    /**
     * store 검증 통과 후 Ok 확정 시점.
     * ⚠ payment에 secret 포함 가능(실측: BILLING 카드 결제도 non-null) — payload 통짜 로깅
     * 금지. 기록 용도는 audit(§3.2)으로(redaction 통과본만 기록된다).
     */
    'payment.confirmed': {
        readonly payment: ConfirmedPayment;
    };
    'payment.confirm-failed': {
        /** parse 단계 실패면 null. */
        readonly orderId: OrderId | null;
        readonly error: CallbackParseError | VerifyCheckoutError | ConfirmError;
    };
    'cancel.executed': {
        readonly outcome: CancelOutcome;
    };
    'cancel.failed': {
        readonly paymentKey: PaymentKey;
        readonly error: CancelError;
    };
    /** billingKey는 payload 원천 부재 — 봉인 원칙 유지(유출 원천 차단). */
    'billing.issued': {
        readonly customerKey: CustomerKey;
    };
    'billing.approved': {
        readonly payment: BillingPayment;
        readonly customerKey: CustomerKey;
    };
    'billing.approve-failed': {
        readonly customerKey: CustomerKey;
        readonly error: BillingApproveError;
    };
    'billing.revoked': {
        readonly customerKey: CustomerKey;
    };
    /** §3.1 depositSecrets 연동. */
    'deposit.secret-saved': {
        readonly orderId: OrderId;
    };
    'deposit.secret-save-failed': {
        readonly orderId: OrderId;
        readonly paymentKey: PaymentKey;
        readonly cause: unknown;
    };
    /** 요약만 — AcceptedWebhook 통짜 전달 대신 secret 제거·타입 순환 회피가 보장되는 최소 필드. */
    'webhook.accepted': {
        readonly trust: 'signature' | 'secret' | 'unverified';
        readonly eventType: string;
        readonly transmissionId: string;
    };
    'webhook.duplicate': {
        readonly transmissionId: string;
    };
    'webhook.rejected': {
        readonly rejection: WebhookRejection;
    };
}

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