TTocler Docs
Dashboard
API reference›Shop API

Checkout & Tocler Pay

Create an order for a buyer and take its payment with Tocler Pay — Tocler’s fee applies exactly as in the shop.

Updated 3 November 2026Live from Tocler
GET /v1/coins Your shop’s API keycheckout:write

The coins and networks this shop can take with Tocler Pay right now. Use one key when you start a payment.

Errors
  • 403 missing_scope — The key lacks checkout:write.
  • 409 tocler_pay_unavailable — Tocler Pay is not open for this shop right now (the message says why).
  • 401 invalid_key — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 429 rate_limited — Over the key’s requests per minute — wait for RateLimit-Reset.
curl -X GET 'https://api.tocler.com/v1/coins' \
  -H 'Authorization: Bearer tk_live_…'
POST /v1/checkout Your shop’s API keycheckout:write

Makes an order in the shop for a buyer’s email, through the shop’s own checkout: live prices, stock held, tax, discount and shipping as in the shop, and Tocler’s fee as in the shop. The buyer is emailed the order. Pay it with Tocler Pay — send the buyer to pay_url (the shop’s own pay page), or start the payment yourself with POST /v1/orders/{id}/tocler-pay and show the address and exact amount in your own page. Keys and accounts show on the order page only after the buyer opens the link in their email. Send an Idempotency-Key header.

  • Idempotency-Keystringheaderrequired
    1–64 letters, digits, _ - : . — the same one when you retry. The same key with another body → 409 idempotency_mismatch.
  • emailstringbodyrequired
    The buyer’s email — the order and its delivery are sent there.
  • itemsarraybodyrequired
    [{ product_id, variant_id?, quantity, answers? }] — up to 50 lines. answers = { "<question id or key>": "value" } for products that ask questions.
  • paymentstringbodyrequired
    "tocler_pay" (the way of paying for API orders).
  • billingobjectbody
    { country: "DE", vat_id? } — required when the shop collects tax.
  • shippingobjectbody
    For physical goods: { address: { name, line1, line2?, city, postcode, region?, country, phone? }, choices: { "<group>": "<rate id>" } }.
  • discount_codestringbody
    A discount code of the shop.
Errors
  • 403 missing_scope — The key lacks checkout:write.
  • 400 invalid_request — A field is missing or wrong (see field).
  • 400 tax_country — The shop collects tax: send billing.country.
  • 400 answer_required — A product needs an answer to its question.
  • 400 shipping_required — Physical goods need a shipping address and a rate.
  • 403 checkout_unavailable — Tocler stopped orders without an account for this shop.
  • 409 tocler_pay_unavailable — Tocler Pay is not open for this shop right now.
  • 409 discount — The discount code can’t be used.
  • 429 too_many_open — Too many unpaid orders for this email or shop.
  • 401 invalid_key — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 429 rate_limited — Over the key’s requests per minute — wait for RateLimit-Reset.
curl -X POST 'https://api.tocler.com/v1/checkout' \
  -H 'Authorization: Bearer tk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "buyer@example.com",
  "payment": "tocler_pay",
  "billing": {
    "country": "DE"
  },
  "items": [
    {
      "product_id": "665f1c2e9b1e8a00aaaaaaaa",
      "variant_id": "665f1c2e9b1e8a00bbbbbbbb",
      "quantity": 2,
      "answers": {
        "player_id": "88231"
      }
    }
  ]
}'
POST /v1/orders/{id}/tocler-pay Your shop’s API keycheckout:write

For an order made with this API that is still waiting: the address, the EXACT amount, the network and the time left. Show them to the buyer (with a QR code of the address). Choosing another coin replaces the waiting payment. The order becomes paid only after Tocler Pay’s checks on the blockchain — follow it with GET /v1/orders/{id} (or the order.paid webhook). Send an Idempotency-Key header.

  • Idempotency-Keystringheaderrequired
    1–64 letters, digits, _ - : . — the same one when you retry. The same key with another body → 409 idempotency_mismatch.
  • idstringpathrequired
    The order id.
  • coinstringbodyrequired
    A coin key from GET /v1/coins.
Errors
  • 403 missing_scope — The key lacks checkout:write.
  • 404 not_found — No such order made with the API in this shop.
  • 409 not_payable — The order is not waiting for a Tocler Pay payment (paid, expired, or made in the shop).
  • 409 coin_unavailable — That coin is not available right now.
  • 409 payment_in_progress — A payment is already on its way — wait for it.
  • 401 invalid_key — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 429 rate_limited — Over the key’s requests per minute — wait for RateLimit-Reset.
curl -X POST 'https://api.tocler.com/v1/orders/{id}/tocler-pay' \
  -H 'Authorization: Bearer tk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "coin": "usdt_tron"
}'
GET /v1/orders/{id}/tocler-pay Your shop’s API keycheckout:write

Asks the blockchain now (at most every 10 seconds) and answers the payment and the order — for an “I have paid” button. The order completes by itself either way.

  • idstringpathrequired
    The order id.
Errors
  • 403 missing_scope — The key lacks checkout:write.
  • 404 not_found — No such order made with the API in this shop.
  • 401 invalid_key — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 429 rate_limited — Over the key’s requests per minute — wait for RateLimit-Reset.
curl -X GET 'https://api.tocler.com/v1/orders/{id}/tocler-pay' \
  -H 'Authorization: Bearer tk_live_…'
Was this page helpful?