ホステッドチェックアウト

Checkout Session

購入者をチェックアウトへ送る前に、注文条件をサーバーに固定します。

Checkout Session は販売者注文の基準データです。購入者が Checkout を開く前に、商品、数量、購入モード、戻り先、販売者の注文参照をサーバーに固定します。

#セッションを作成

POST/api/v2/checkout-sessions/

商品所有者のバックエンドから販売者 JWT で呼び出します。商品はその販売者が所有する販売中の商品で、検証済み 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"