TTocler Docs
Dashboard
API reference›Tocler Pay API

Payments

Create, read, check, cancel and list payments.

Updated 2 November 2026Live from Tocler
POST /api/pay/v1/payments Your Tocler Pay merchant keypayments:create

Create a payment. Answers 201 with the payment. The same reference + coin + amount returns the same waiting payment; another coin for the same reference cancels the waiting one. While a payment for the reference is confirming / in review, or after it was paid → 409.

  • Idempotency-Keystringheader
    Strongly advised — 1–64 letters, digits, _ - : .
  • amount_usdstringbodyrequired
    "25.00" — at least 0.50.
  • coinstringbodyrequired
    A key from GET /v1/coins.
  • referencestringbodyrequired
    Your order / invoice id (1–64: letters, digits, . _ : -). A reference can be paid once.
  • address_modestringbody
    tocler or own — needed when the key has both.
  • payeestringbody
    Own mode: a sub-account whose own addresses are used.
  • metadataobjectbody
    Up to 20 keys (letters, digits, _ -); values text ≤ 500, number or true / false. Never secrets.
Errors
  • 400 invalid_request — A field is missing or wrong — see error.field.
  • 400 amount_too_small — Under $0.50.
  • 400 amount_over_key_limit — Over the key’s most per payment.
  • 400 daily_limit_reached — The key’s 24-hour limit is used up.
  • 401 unauthorized — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 403 missing_scope — The key lacks the scope this call needs.
  • 403 coin_not_allowed — The key may not use that coin.
  • 409 reference_paid — That reference was already paid.
  • 409 payment_in_progress — A payment for the reference is confirming or in review.
  • 409 coin_unavailable — The coin is off or has no ready address.
  • 409 idempotency_mismatch — The same Idempotency-Key with another body.
  • 429 rate_limited — Too many requests — slow down and try again.
curl -X POST 'https://api.tocler.com/api/pay/v1/payments' \
  -H 'Authorization: Bearer tp_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_usd": "25.00",
  "coin": "usdt_tron",
  "reference": "order-1001",
  "address_mode": "own",
  "metadata": {
    "cart": "c-9"
  }
}'
statusMeaning
pendingWaiting for the transfer.
confirmingSeen on the chain; waiting for confirmations.needed.
paidAll 5 checks passed — deliver.
expiredThe timer ended with nothing received.
reviewSomething odd (late, after a cancel, not the exact amount) — Tocler decides.
refusedRefused after review.
cancelledCancelled by you, by another coin chosen, or when the order closed.
GET /api/pay/v1/payments/{id} Your Tocler Pay merchant keypayments:read

One payment. Always read the payment back before delivering — never act on a webhook alone.

  • idstringpathrequired
    The payment id, e.g. TCP-7KQ2M9XA.
Errors
  • 401 unauthorized — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 403 missing_scope — The key lacks the scope this call needs.
  • 404 not_found — No such object, or it belongs to another merchant.
curl -X GET 'https://api.tocler.com/api/pay/v1/payments/{id}' \
  -H 'Authorization: Bearer tp_live_…'
POST /api/pay/v1/payments/{id}/check Your Tocler Pay merchant keypayments:read

Ask the blockchain now, then answer the payment — for a “I have paid” button. At most once every 10 seconds per payment.

  • idstringpathrequired
    The payment id.
Errors
  • 401 unauthorized — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 403 missing_scope — The key lacks the scope this call needs.
  • 404 not_found — No such object, or it belongs to another merchant.
  • 429 rate_limited — Too many requests — slow down and try again.
curl -X POST 'https://api.tocler.com/api/pay/v1/payments/{id}/check' \
  -H 'Authorization: Bearer tp_live_…'
POST /api/pay/v1/payments/{id}/cancel Your Tocler Pay merchant keypayments:cancel

Cancel a pending payment. A transfer that still arrives goes to review.

  • idstringpathrequired
    The payment id.
Errors
  • 401 unauthorized — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 403 missing_scope — The key lacks the scope this call needs.
  • 404 not_found — No such object, or it belongs to another merchant.
  • 409 not_cancellable — Only a pending payment can be cancelled.
curl -X POST 'https://api.tocler.com/api/pay/v1/payments/{id}/cancel' \
  -H 'Authorization: Bearer tp_live_…'
GET /api/pay/v1/payments Your Tocler Pay merchant keypayments:read

List payments, newest first.

  • referencestringquery
    Exactly this reference.
  • reference_prefixstringquery
    References starting with this.
  • statusstringquery
    One status.
  • limitintegerquery
    Up to 100.
  • created_beforestringquery
    Paging: pass next_created_before from the last answer.
Errors
  • 400 invalid_request — A field is missing or wrong — see error.field.
  • 401 unauthorized — No key, a wrong key, or a revoked / expired key (key_revoked, key_expired).
  • 403 missing_scope — The key lacks the scope this call needs.
curl -X GET 'https://api.tocler.com/api/pay/v1/payments' \
  -H 'Authorization: Bearer tp_live_…'
Was this page helpful?