TossCancels — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/** 취소 실행 네임스페이스 — TossServerClient.cancels 의 타입. */
interface TossCancels<E extends Env> {
    /**
     * 전액 환불. expectedAmount는 필수이며 **호출자 장부(자체 DB)의 기대 금액**이어야 한다 —
     * 서버 balanceAmount(= target.balanceAmount)를 되돌려 넣으면 검증이 항진식이 된다.
     * 불일치 시 API 호출 전 Err. refundableAmount는 항상 자동 전송(서버 낙관적 잠금).
     * 멱등키 미지정 시 실행 전에 UUID 생성·body와 함께 봉인 — 실패 시 retry 티켓으로 회수.
     * ⚠ 유니언 오버로드 없음 — kind 내로잉 없이는 호출 자체가 컴파일 에러.
     */
    cancelFully(target: SettledCancelable, request: {
        readonly reason: CancelReason;
        readonly expectedAmount: number;
        /** 가상계좌 아님 — 변수/스프레드 경유도 차단. */
        readonly refundAccount?: never;
        readonly taxFreeAmount?: number;
        readonly currency?: 'KRW' | 'USD' | 'JPY';
        /** 중국·동남아 비동기(Alipay 등) 결제 취소에만 필수 — 상점 발급 고유값(문서 ID 53 §5). */
        readonly cancelRequestId?: CancelRequestId;
    }, options?: CallOptions<E>): Promise<Result<CancelOutcome, CancelError>>;
    cancelFully(target: DepositedVaCancelable, request: {
        readonly reason: CancelReason;
        readonly expectedAmount: number;
        /** 입금 완료 가상계좌 — 필수. */
        readonly refundAccount: RefundAccount;
        readonly taxFreeAmount?: number;
        readonly currency?: 'KRW' | 'USD' | 'JPY';
        /** 중국·동남아 비동기(Alipay 등) 결제 취소에만 필수 — 상점 발급 고유값(문서 ID 53 §5). */
        readonly cancelRequestId?: CancelRequestId;
    }, options?: CallOptions<E>): Promise<Result<CancelOutcome, CancelError>>;
    cancelFully(target: AwaitingDepositCancelable, request: {
        readonly reason: CancelReason;
        readonly expectedAmount: number;
        /** 입금 전 — 환불할 금액이 없으므로 금지. */
        readonly refundAccount?: never;
        /** 중국·동남아 비동기(Alipay 등) 결제 취소에만 필수 — 상점 발급 고유값(문서 ID 53 §5). */
        readonly cancelRequestId?: CancelRequestId;
    }, options?: CallOptions<E>): Promise<Result<CancelOutcome, CancelError>>;
    /**
     * 부분 환불. AwaitingDepositCancelable 오버로드 없음 → 입금 전 부분취소는 컴파일 에러
     * (서버: NOT_ALLOWED_PARTIAL_REFUND_WAITING_DEPOSIT). 사전검증: amount ≤ balanceAmount.
     */
    cancelPartially(target: Extract<SettledCancelable, {
        readonly partialAllowed: true;
    }>, request: {
        readonly reason: CancelReason;
        readonly amount: number;
        readonly refundAccount?: never;
        readonly taxFreeAmount?: number;
        readonly currency?: 'KRW' | 'USD' | 'JPY';
        /** 중국·동남아 비동기(Alipay 등) 결제 취소에만 필수 — 상점 발급 고유값(문서 ID 53 §5). */
        readonly cancelRequestId?: CancelRequestId;
    }, options?: CallOptions<E>): Promise<Result<CancelOutcome, CancelError>>;
    cancelPartially(target: Extract<DepositedVaCancelable, {
        readonly partialAllowed: true;
    }>, request: {
        readonly reason: CancelReason;
        readonly amount: number;
        readonly refundAccount: RefundAccount;
        readonly taxFreeAmount?: number;
        readonly currency?: 'KRW' | 'USD' | 'JPY';
        /** 중국·동남아 비동기(Alipay 등) 결제 취소에만 필수 — 상점 발급 고유값(문서 ID 53 §5). */
        readonly cancelRequestId?: CancelRequestId;
    }, options?: CallOptions<E>): Promise<Result<CancelOutcome, CancelError>>;
    /** transport 실패 티켓 재실행 — 봉인된 동일 멱등키+body. 서버에 도달했었다면 멱등 재생, 아니면 재실행. */
    retry(ticket: CancelRetryTicket, options?: Pick<CallOptions<E>, 'signal'>): Promise<Result<CancelOutcome, CancelError>>;
    /** 영속 CancelRetryStore의 opaque ticketId로 프로세스 재시작 후 재실행. */
    retryById(ticketId: string, options?: Pick<CallOptions<E>, 'signal'>): Promise<Result<CancelOutcome, CancelError>>;
}

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

Release context

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

구현 주석

취소 실행 네임스페이스 — TossServerClient.cancels 의 타입.