Create an NFT Checkout

Checkout sessions must be created by the store backend. Never put the Belong API key in storefront code.

Endpoint

POST https://api.belong.net/api/v3/checkout/sessions
Content-Type: application/json
x-api-key: YOUR_SERVER_API_KEY

Request

{
  "collectionId": "65f1c7a33e51d8e4c2a9b4d2",
  "externalOrderId": "shopify:order:89351",
  "items": [
    {
      "name": "Partner Product NFT",
      "description": "Digital proof of purchase",
      "mintPrice": 49,
      "image": "https://shop.example/assets/product-nft.png",
      "externalProductRef": "shopify:variant:4471",
      "quantity": 1
    }
  ],
  "paymentMethods": ["crypto_wallet"],
  "allowedOrigin": "https://shop.example",
  "webhookUrl": "https://shop.example/api/belong/webhook",
  "expiresInSeconds": 1800
}

The pilot accepts one item with quantity 1. externalOrderId is idempotent for the API-key owner: repeating the same request returns the same checkout, while different data for the same order returns 409.

mintPrice is the amount in the payment token configured on the collection. The backend stores this snapshot and ignores any collection, item, receiver, or price sent later by the browser.

Use a dynamic-price collection when store products have different prices. With a static-price collection, mintPrice must equal the collection's configured mint price.

For the first partner, use only crypto_wallet. Add thirdweb_card only after Belong enables and verifies that method for the merchant and network.

Response

{
  "checkoutId": "65f1c7c8d4a5b3e9f8c1d2e3",
  "clientSecret": "checkout_client_secret",
  "checkoutUrl": "https://checkin.belong.net/checkout/65f1c7c8d4a5b3e9f8c1d2e3#clientSecret=checkout_client_secret",
  "webhookSecret": "webhook_signing_secret",
  "status": "PENDING",
  "expiresAt": "2026-09-08T15:00:00.000Z"
}

Return checkoutId and clientSecret to the storefront that requested the order. Store webhookSecret only on the server and use it to verify webhook signatures.