Hosted Checkout

Checkout Sessions

Create a server-bound order before sending a buyer to checkout.

A Checkout Session is the authoritative merchant order. It binds product, quantity, purchase mode, return destination, and merchant reference before the buyer opens Checkout.

#Create a session

POST/api/v2/checkout-sessions/

Call this endpoint from the product owner’s backend with a seller JWT. The product must be active, owned by that seller, and linked to a 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"
  }'

#Request fields

Field	Required	Description
`product_id`	Required	Active RANTAN product ID owned by the authenticated seller.
`client_reference_id`	Required	Unique merchant order reference, up to 200 characters.
`quantity`	Optional	Purchase quantity. Defaults to 1.
`return_url`	Optional	HTTPS URL to receive the buyer after Checkout.
`allowed_origin`	Optional	Allowed browser origin. Must match the return_url origin when both are present.
`digital_mode`	Optional	For digital products, use requests when purchasing request credits.
`request_amount`	Optional	Number of digital requests. Required when digital_mode is requests.

#Digital request credits

Digital products can bind a request-credit purchase to the session. Non-digital products reject digital_mode and 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"
}

#Idempotency

Session creation is idempotent per seller and client_reference_id. Repeating the same request returns the existing session and verification key.

#Cancel an open session

Cancel when the external order is abandoned. The operation is idempotent while the session is still open.

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"