Verify Checkout

Verification is the authority for fulfillment. Browser redirects and popup messages are intentionally untrusted hints.

#Verify from your backend

Authenticate with the server-only verification key returned during session creation. The product owner can alternatively use the seller JWT.

curl https://app.rantan.xyz/api/v2/checkout-sessions/$SESSION_ID/verify/ \
  -H "X-Rantan-Checkout-Verification-Key: $CHECKOUT_VERIFICATION_KEY"

#Verification response

The endpoint returns both session state and the bound purchase state. An open or expired session returns completed=false.

{
  "checkout_session_id": "c8a9d48e-68b2-48dd-a754-75635cae71d6",
  "client_reference_id": "order_20260730_001",
  "product_id": 123,
  "purchase_id": "bfaf2aa4-dd86-4356-92db-ae0431806867",
  "purchase_status": "completed",
  "completed": true,
  "buyer_wallet_address": "0x1234...abcd",
  "quantity": 1,
  "currency": "USDC",
  "total_amount": "12.50000000",
  "amount_atomic": "12500000",
  "completed_at": "2026-07-30T09:04:32Z",
  "error_message": "",
  "session_status": "completed",
  "canceled_at": null,
  "expires_at": "2026-07-30T09:30:00Z"
}

#Fulfillment checklist

1. 1
   Require a completed purchase

   completed is true and purchase_status is completed.

2. 2
   Match your order

   client_reference_id, product_id, quantity, currency, and expected amount match your stored order.

3. 3
   Consume once

   Store purchase_id with a uniqueness constraint before granting access or shipping.

4. 4
   Record the evidence

   Keep checkout_session_id, purchase_id, completed_at, and the verified amount with the merchant order.

#Return URL hints

RANTAN appends rantan_checkout_session_id, rantan_purchase_id, and rantan_purchase_status to the configured return_url.

#Safe retries

Verification is read-only and can be retried. Make the merchant fulfillment operation idempotent around purchase_id so repeated callbacks cannot duplicate access, delivery, or credits.