Tocler Pay API — introduction
Base address, keys, scopes, errors, idempotency and limits.
| What | Value |
|---|---|
| Base address | https://api.tocler.com/api/pay — every path starts with /v1/ |
| Format | JSON in and out, UTF-8, request bodies up to 32 KB |
| Authentication | Authorization: Bearer tp_live_<id>.<secret> on every request |
| Where | Server to server only — never in a browser or an app |
Keys and their features
Each key has scopes (payments:create, payments:read, payments:cancel, addresses:read, addresses:write), address modes (tocler = Tocler Pay’s addresses, only for merchants Tocler allows; own = your addresses), allowed coins, a most per payment and a daily limit in USD, allowed IPs, requests per minute (120 by default) and an optional expiry date. Keys are stored only as a keyed hash — a lost key can’t be shown again: revoke it and make a new one.
Errors
Every error has an HTTP status and a stable code:
{ "error": { "code": "amount_too_small", "message": "The smallest payment is $0.50.", "field": "amount_usd" } }| Status | Codes | When |
|---|---|---|
| 400 | invalid_request · amount_too_small · amount_over_key_limit · daily_limit_reached · invalid_address | A field or an amount rule |
| 401 | unauthorized · key_revoked · key_expired | The key |
| 403 | missing_scope · address_mode_not_allowed · coin_not_allowed · ip_not_allowed · merchant_suspended | The key’s features |
| 404 | not_found | No such object (or not yours) |
| 409 | reference_paid · payment_in_progress · coin_unavailable · not_cancellable · idempotency_mismatch · request_in_progress | The state |
| 429 | rate_limited | Slow down |
| 500 / 503 | server_error · unavailable | Try again later with the same Idempotency-Key |
Idempotency
Send Idempotency-Key: <1–64 letters, digits, _ - : .> with every POST. The same key and body return the first answer for 24 hours (header Idempotent-Replayed: true); the same key with another body answers 409 idempotency_mismatch.