resolveConfirmFailure — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * confirm 실패를 조회 기반으로 판정한다 (설계 §3.7 확정 로직):
 * - `source === 'network'`(transport) 또는 `ALREADY_PROCESSED_PAYMENT` →
 *   `getPaymentByOrderId` 조회 → status가 DONE|WAITING_FOR_DEPOSIT이면 결제를 확인한다.
 *   단, 가상계좌 조회의 `secret:null`은 정상 응답이므로
 *   'confirmed-without-deposit-secret'으로 명시한다.
 * - `NOT_FOUND_PAYMENT_SESSION`(10분 초과 — 라이브러리 시한 초과 에러 동일 취급) →
 *   조회 없이 'retry-payment'.
 * - 그 외 REJECT/AUTH 계열 → 조회 없이 'definitively-failed'.
 *
 * ⚠ 조회 자체가 Err면 진실 미확정이다 — **성공/실패 어느 쪽으로도 사용자에게 단정 안내하지
 * 말 것**(재시도 또는 수동 확인으로 넘겨라).
 *
 * 미해결(Phase 6 실측 항목): ALREADY_PROCESSED_PAYMENT인데 조회 status가 CANCELED인 희귀
 * 케이스(다른 경로로 이미 취소) — 현재는 'definitively-failed'로 분류된다.
 */
declare function resolveConfirmFailure<E extends Env>(client: Pick<TossServerClient<E>, 'getPaymentByOrderId'>, orderId: OrderId, error: ConfirmError): Promise<Result<ConfirmResolution, LookupError$1>>;

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

Release context

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

구현 주석

confirm 실패를 조회 기반으로 판정한다 (설계 §3.7 확정 로직):

• source === 'network'(transport) 또는 ALREADY_PROCESSED_PAYMENT → getPaymentByOrderId 조회 → status가 DONE|WAITING_FOR_DEPOSIT이면 결제를 확인한다. 단, 가상계좌 조회의 secret:null은 정상 응답이므로 ’confirmed-without-deposit-secret’으로 명시한다.
• NOT_FOUND_PAYMENT_SESSION(10분 초과 — 라이브러리 시한 초과 에러 동일 취급) → 조회 없이 ‘retry-payment’.
• 그 외 REJECT/AUTH 계열 → 조회 없이 ‘definitively-failed’.

⚠ 조회 자체가 Err면 진실 미확정이다 — 성공/실패 어느 쪽으로도 사용자에게 단정 안내하지 말 것(재시도 또는 수동 확인으로 넘겨라).

미해결(Phase 6 실측 항목): ALREADY_PROCESSED_PAYMENT인데 조회 status가 CANCELED인 희귀 케이스(다른 경로로 이미 취소) — 현재는 ’definitively-failed’로 분류된다.