PaymentStatusChangedEvent — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * 웹훅 이벤트 타입 + 신뢰 3등급 + 전방 호환 UNKNOWN 래퍼.
 *
 * '검증됨' 단일 타입은 의도적으로 없다 — 토스가 전 이벤트에 서명을 제공하지 않는다:
 * 서명(HMAC)은 payout.changed/seller.changed에만, secret 대조는 DEPOSIT_CALLBACK에만
 * 존재하고 나머지는 암호학적 진위 검증 수단이 없다.
 * 출처: docs/research/toss-payments-v2.md "웹훅과 보안".
 */
interface PaymentStatusChangedEvent {
    readonly envelope: 'legacy';
    readonly eventType: 'PAYMENT_STATUS_CHANGED';
    /** 마이크로초 6자리 무오프셋 형식(yyyy-MM-dd'T'HH:mm:ss.SSSSSS) — {@link import('./envelope').parseTossTimestamp} 권장. */
    readonly createdAt: string;
    /**
     * core Payment 재사용(웹훅 전용 타입의 이중 관리 회피) + 종결 status 협착 —
     * 문서: EXPIRED/DONE/ABORTED/CANCELED/PARTIAL_CANCELED로의 전이 시에만 발송된다.
     */
    readonly data: Payment & {
        readonly status: 'DONE' | 'CANCELED' | 'PARTIAL_CANCELED' | 'ABORTED' | 'EXPIRED';
    };
}

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

Release context

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

구현 주석

웹훅 이벤트 타입 + 신뢰 3등급 + 전방 호환 UNKNOWN 래퍼.

‘검증됨’ 단일 타입은 의도적으로 없다 — 토스가 전 이벤트에 서명을 제공하지 않는다: 서명(HMAC)은 payout.changed/seller.changed에만, secret 대조는 DEPOSIT_CALLBACK에만 존재하고 나머지는 암호학적 진위 검증 수단이 없다. 출처: docs/research/toss-payments-v2.md “웹훅과 보안”.