주문
CheckoutSession이 구매자가 보는 것이라면, Order는 가맹점이 신경 쓰는 대상입니다. 다음의 영구 기록입니다.
- 구매되는 항목(라인 아이템)
- 청구된 금액과 실제로 결제된 금액
- 미해결 및 적용된 환불
- 외부 참조(
external_ref) — 일반적으로 가맹점의 자체 주문 ID로, Order에 저장되며GET /b2b/v1/orders/{id}에서 반환됩니다(웹훅 페이로드에는 노출되지 않음 — 아래 참조)
CheckoutSession은 자체 PaymentIntent 중 하나가 정산되거나 TTL이 만료되면 사라집니다. Order는 영구적으로 존재합니다.
Order가 생성되는 시점
POST /b2b/v1/checkout-sessions/quick을 호출하면 payment-service가 단일
트랜잭션에서 새 Order와 새 CheckoutSession을 함께 생성합니다. 이미
Order가 있고 체크아웃을 재시도하려는 경우(예: 구매자가 포기한 후),
POST /b2b/v1/checkout-sessions를 대신 사용하여 기존 주문에 새 세션을
연결하세요 — 감사 추적이 유지됩니다.
라이프사이클
| 상태 | 의미 |
|---|---|
DRAFT | 향후 드래프트 흐름을 위해 예약됨. 현재 어떤 코드 경로도 DRAFT 주문을 생성하지 않습니다 — 모든 주문은 PENDING 상태로 생성되므로 이 상태를 관찰할 일은 없습니다. |
PENDING | CheckoutSession이 활성 상태이며 미해결입니다. |
PAID | 전체 금액이 정산됨. 여기서 payment.settled 웹훅이 발생합니다. 이행 처리에 안전한 상태입니다. |
PARTIAL_PAID | 자금이 도착했지만 총액보다 적음. 아래 “과소 결제” 참조. |
CANCELED | 세션이 만료되었거나 가맹점이 취소함. metadata.canceled_reason가 이유를 설명합니다(payment_timeout, merchant_canceled 등). |
REFUNDED | 결제된 전체 금액이 환불됨. |
PARTIALLY_REFUNDED | 일부 환불이 실행되었지만 잔액은 결제 상태로 유지됨. |
이행 로직을 트리거할 상태는 CheckoutSession의 COMPLETED가 아닌 PAID입니다.
payment.settled 웹훅이 정식 신호입니다.
external_ref 필드
세션 생성 시 external_ref(최대 255자의 임의 문자열 — 일반적으로 가맹점의
자체 주문 ID)를 포함할 수 있습니다. 전체 파이프라인을 통해 전달됩니다.
- Order에 저장됨
- 지원 조회를 위해 가맹점 대시보드에 표시됨
GET /b2b/v1/orders/{id}에서 반환되므로 웹훅 핸들러가payment.settled를 수신한 후 가져올 수 있음
현재 웹훅 페이로드는 external_ref를 직접 노출하지 않습니다 — 이
문서의 초기 초안에서 data.external_ref가 모든 이벤트로 전달된다고
주장했지만, 이는 잘못된 내용이었습니다. payment.* 웹훅을 가맹점 DB
행과 매핑하려면 페이로드의 order_id를 사용하여 주문을 가져오세요.
웹훅 페이로드의 네이티브 external_ref 필드는 로드맵에 있습니다.
과소 결제
구매자의 온체인 송금이 주문 총액보다 적은 금액으로 완료되면 Order는
PARTIAL_PAID로 이동합니다. 세 가지 옵션이 있습니다.
- 수용 및 해결. 주문을
PAID로 전환하고order.resolved를 발생시킵니다. 이는 공개 REST 엔드포인트가 아닙니다 — 해결은 현재 내부/운영 작업이므로, 셀프 서비스 흐름에서는 옵션 2(부족분 수집)를 선호하세요. - 부족분 대기. 동일한 Order에 대해
amount_due= 잔여 금액으로 새 CheckoutSession을 생성합니다. 구매자가 차액을 결제하면 정산 시 Order가PAID로 이동합니다. - 취소 및 환불. 부분 금액을 환불하고 Order를 취소합니다. 구매자가 체인 수수료를 부담해야 합니다.
제품 차원에서 권장 방식은 정해져 있지 않습니다 — 가맹점마다 다른 정책을 선호합니다. 하나를 선택하여 어드민에 반영하세요.
환불
환불은 별도의 API 표면과 별도의 개념 페이지가 있습니다. 개념 → 환불을 참조하세요.
API 엔드포인트
| 메서드 | 경로 | 비고 |
|---|---|---|
POST | /b2b/v1/orders | 세션 없이 Order 생성(드뭄) |
GET | /b2b/v1/orders/:order_id | 라인 아이템 + 결제 이력을 포함한 전체 주문 읽기 |
PATCH | /b2b/v1/orders/:order_id/cancel | 미결제 주문 취소 |
PATCH | /b2b/v1/orders/:order_id/reopen | 자동 취소된(payment_timeout) 주문 재오픈 |