호스티드 체크아웃

Checkout Session

구매자를 체크아웃으로 보내기 전에 서버에 주문 조건을 고정합니다.

Checkout Session은 판매자 주문의 기준 데이터입니다. 구매자가 Checkout을 열기 전에 상품, 수량, 구매 모드, 반환 주소, 판매자 주문 참조값을 서버에 고정합니다.

#세션 생성

POST/api/v2/checkout-sessions/

상품 소유자의 백엔드에서 판매자 JWT로 호출합니다. 상품은 해당 판매자가 소유한 판매 중 상품이어야 하며 Verified RANTAN Factory NFT가 연결돼야 합니다.

Create session

curl -X POST https://app.rantan.xyz/api/v2/checkout-sessions/ \
  -H "Authorization: Bearer $RANTAN_SELLER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "client_reference_id": "order_20260730_001",
    "quantity": 1,
    "return_url": "https://merchant.example/orders/20260730_001",
    "allowed_origin": "https://merchant.example"
  }'

#요청 필드

필드	필수 여부	설명
`product_id`	필수	인증된 판매자가 소유한 판매 중 RANTAN 상품 ID입니다.
`client_reference_id`	필수	판매자 주문 시스템의 고유 참조값이며 최대 200자입니다.
`quantity`	선택	구매 수량이며 기본값은 1입니다.
`return_url`	선택	Checkout 후 구매자를 돌려보낼 HTTPS URL입니다.
`allowed_origin`	선택	허용할 브라우저 origin입니다. return_url과 함께 사용하면 origin이 같아야 합니다.
`digital_mode`	선택	디지털 상품의 요청 크레딧 구매에는 requests를 사용합니다.
`request_amount`	선택	디지털 요청 수입니다. digital_mode가 requests일 때 필요합니다.

#디지털 요청 크레딧

디지털 상품은 요청 크레딧 구매 조건을 세션에 고정할 수 있습니다. 디지털이 아닌 상품은 digital_mode와 request_amount를 거부합니다.

Digital product

{
  "product_id": 123,
  "client_reference_id": "credits_20260730_001",
  "quantity": 1,
  "digital_mode": "requests",
  "request_amount": 100,
  "return_url": "https://merchant.example/orders/credits_20260730_001",
  "allowed_origin": "https://merchant.example"
}

#멱등성

세션 생성은 판매자와 client_reference_id 조합으로 멱등 처리됩니다. 같은 요청을 반복하면 기존 세션과 검증 키를 반환합니다.

#열린 세션 취소

외부 주문이 취소되면 세션을 무효화합니다. 세션이 열린 상태에서는 반복 호출해도 같은 결과를 반환합니다.

DELETE/api/v2/checkout-sessions/{sessionId}/

Cancel session

curl -X DELETE \
  https://app.rantan.xyz/api/v2/checkout-sessions/$SESSION_ID/ \
  -H "Authorization: Bearer $RANTAN_SELLER_JWT"