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

Signature, parameters, and return type

/** 취소 실행 네임스페이스 — 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>>;
}

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