Checkout

Create payment links, collect Pix, and track orders through the Hodle API.

Checkout creates hosted Pix payment links. Manage products and settlement settings, or use the payer endpoints from your backend to build your own checkout UI. The hosted page needs no API key.

Authentication and availability

Every REST endpoint, seller and payer, requires your production API key:

Authorization: Bearer hodle_live_...

Checkout is enabled per account (ask support) and requires an available settlement asset. Each endpoint acts on your account's products and orders. Keep the API key on your server and call the REST API from your backend.

Seller endpoints

GET /api/checkout/products

Lists products owned by the account behind the API key, newest first.

curl --request GET \
  --url https://api.hodle.com.br/api/checkout/products \
  --header "Authorization: Bearer $HODLE_API_KEY"
{
  "success": true,
  "data": {
    "products": [
      {
        "id": "68bb089d3696d243ba022bc1",
        "slug": "plano-premium-k7m2p4",
        "name": "Plano Premium",
        "description": "Acesso por 30 dias",
        "imageUrl": null,
        "priceCents": 8990,
        "stock": null,
        "sold": 12,
        "views": 84,
        "asset": "BRLA",
        "network": "polygon",
        "askEmail": true,
        "askTaxId": true,
        "askNote": false,
        "status": "ACTIVE",
        "createdAt": "2026-09-05T13:00:00.000Z",
        "updatedAt": "2026-09-05T13:00:00.000Z"
      }
    ]
  }
}

POST /api/checkout/products

Publishes one product. The settlement asset and network come from the current Checkout settings and cannot be passed in this request.

curl --request POST \
  --url https://api.hodle.com.br/api/checkout/products \
  --header "Authorization: Bearer $HODLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Plano Premium",
    "description": "Acesso por 30 dias",
    "priceCents": 8990,
    "stock": null,
    "askTaxId": true,
    "askNote": false
  }'
const response = await fetch('https://api.hodle.com.br/api/checkout/products', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Plano Premium',
    description: 'Acesso por 30 dias',
    priceCents: 8990,
    stock: null,
    askTaxId: true,
    askNote: false,
  }),
})

const { data } = await response.json()
import os, requests

response = requests.post(
    "https://api.hodle.com.br/api/checkout/products",
    headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
    json={
        "name": "Plano Premium",
        "description": "Acesso por 30 dias",
        "priceCents": 8990,
        "stock": None,
        "askTaxId": True,
        "askNote": False,
    },
)

product = response.json()["data"]["product"]
FieldTypeRequiredDescription
namestringyesProduct name, up to 120 characters.
descriptionstringnoDescription, up to 240 characters.
imageBase64data URInoPNG, JPEG, or WEBP image as a base64 data URI.
priceCentsintegeryesUnit price in BRL cents. From 100 to 100000000.
stockinteger / nullnoTotal sellable units. null or omission means unlimited stock.
askTaxIdbooleannoAlways true; payer CPF/CNPJ is required regardless of this value.
askNotebooleannoAllow a payer note of up to 140 characters. Defaults to false.

Returns 201 with data.product in the same shape as the list endpoint.

PATCH /api/checkout/products/:productId

Updates an owned product. Send at least one field:

curl --request PATCH \
  --url https://api.hodle.com.br/api/checkout/products/68bb089d3696d243ba022bc1 \
  --header "Authorization: Bearer $HODLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"priceCents": 9490, "status": "PAUSED"}'
FieldTypeValues
priceCentsintegerBRL cents, from 100 to 100000000.
stockinteger / nullNon-negative, or null for unlimited.
statusstringDRAFT, ACTIVE, or PAUSED.

GET /api/checkout/settings

Returns the effective settlement configuration and which assets the account is currently allowed to select.

{
  "success": true,
  "data": {
    "settings": {
      "displayName": "Hodle Store",
      "supportEmail": "support@example.com",
      "asset": "USDC",
      "network": "polygon",
      "availableAssets": ["BRLA", "USDT", "USDC", "BRS"]
    }
  }
}

PUT /api/checkout/settings

curl --request PUT \
  --url https://api.hodle.com.br/api/checkout/settings \
  --header "Authorization: Bearer $HODLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "displayName": "Hodle Store",
    "supportEmail": "support@example.com",
    "asset": "USDC"
  }'

asset must be present in availableAssets. The server selects the matching network; clients do not pass one. The response contains the saved effective settings.

Payer endpoints

GET /api/public/checkout/products/:slug

Reads the payer-safe view of an active payment link.

curl --request GET \
  --url https://api.hodle.com.br/api/public/checkout/products/plano-premium-k7m2p4 \
  --header "Authorization: Bearer $HODLE_API_KEY"
{
  "success": true,
  "data": {
    "product": {
      "slug": "plano-premium-k7m2p4",
      "name": "Plano Premium",
      "description": "Acesso por 30 dias",
      "imageUrl": null,
      "priceCents": 8990,
      "available": null,
      "soldOut": false,
      "askTaxId": true,
      "askNote": false,
      "sellerName": "Hodle Store",
      "sellerSupportEmail": "support@example.com"
    }
  }
}

POST /api/public/checkout/orders

Creates a Pix charge using the product's price, settlement asset and destination. Send only the fields below.

curl --request POST \
  --url https://api.hodle.com.br/api/public/checkout/orders \
  --header "Authorization: Bearer $HODLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "slug": "plano-premium-k7m2p4",
    "quantity": 1,
    "payerEmail": "buyer@example.com",
    "payerTaxId": "52998224725",
    "payerNote": "Pedido 781"
  }'
const response = await fetch(
  'https://api.hodle.com.br/api/public/checkout/orders',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      slug: 'plano-premium-k7m2p4',
      quantity: 1,
      payerEmail: 'buyer@example.com',
      payerTaxId: '52998224725',
      payerNote: 'Pedido 781',
    }),
  },
)

const order = (await response.json()).data.order
import os

import requests

response = requests.post(
    "https://api.hodle.com.br/api/public/checkout/orders",
    headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
    json={
        "slug": "plano-premium-k7m2p4",
        "quantity": 1,
        "payerEmail": "buyer@example.com",
        "payerTaxId": "52998224725",
        "payerNote": "Pedido 781",
    },
)

order = response.json()["data"]["order"]
FieldTypeRequiredDescription
slugstringyesProduct slug from the public product endpoint.
quantityintegeryesFrom 1 to 99, subject to available stock.
payerEmailstringyesE-mail recorded on the order.
payerTaxIdstringyesValid payer CPF/CNPJ.
payerNotestringnoOptional note, up to 140 characters.

The call returns 201 after the Pix charge is created:

{
  "success": true,
  "data": {
    "order": {
      "trackId": "f28bce4e-2f86-413e-a669-8ad74ae45a91",
      "status": "PENDING",
      "brCode": "00020126580014br.gov.bcb.pix...",
      "quantity": 1,
      "totalCents": 8990,
      "payerEmail": "buyer@example.com",
      "expiresAt": "2026-09-05T14:15:00.000Z",
      "paidAt": null
    }
  }
}

GET /api/public/checkout/orders/:trackId

Poll until the order reaches PAID, FAILED or EXPIRED.

curl --request GET \
  --url https://api.hodle.com.br/api/public/checkout/orders/f28bce4e-2f86-413e-a669-8ad74ae45a91 \
  --header "Authorization: Bearer $HODLE_API_KEY"
StatusMeaning
PENDINGPix is waiting for payment.
PAIDPayment completed.
FAILEDCharge failed.
EXPIREDThe 15-minute Pix payment window expired.

The response has the same data.order shape returned by order creation.

Errors

StatusWhen
400Invalid JSON, undocumented fields, validation error, or unavailable asset.
401Missing or invalid API key.
403Checkout is disabled or the seller has no available settlement rail.
404Product, order or account not found under your key, or a GET payment link is unavailable (including paused links).
409Product is paused or sold out.
429API-key or public-IP rate limit exceeded.
502Pix charge could not be created.

Hosted page

You can use these endpoints from your own UI, or send the payer to Hodle's hosted page:

https://checkout.hodle.com.br/pay/:slug

The hosted page uses the same products and orders as the REST API.