Developers
TorPayment API documentation
Create invoices, receive signed callbacks, give customers permanent deposit addresses and send withdrawals — with plain HTTPS requests from any language.
Overview
The TorPayment API lets your site create invoices, read their state, give customers permanent deposit addresses and — when you switch it on — send withdrawals. It is plain HTTPS: every endpoint answers JSON, and every parameter can be sent in the query string, so a simple GET request is enough. Endpoints marked POST also accept the parameters in a form-encoded (application/x-www-form-urlencoded) or JSON body; when a parameter is in both, the body wins.
- Create a shop in the merchant panel and copy its API key.
- Connect a wallet for every network you want to be paid in. A currency without a wallet cannot be used (error 110).
- Send requests to the base URL below and handle the callbacks your server receives.
Authentication
Every request carries the shop’s API key, in one of three ways (checked in this order):
- the
api_keyparameter, in the query string or the body; - the header
X-Api-Key: <key>; - the header
Authorization: Bearer <key>.
A missing or wrong key, a disabled shop and a disabled account all answer 401 (code 101). If the shop has an IP allowlist (a shop setting in the panel), requests from other addresses answer 403 (code 102). While the account’s one-time access fee is unpaid, every request answers 402 (code 124).
The API key is also the secret that signs callbacks (verify_hash, X-TorPayment-Signature). Keep it on your server only. The gateway leaves keys out of the URLs it logs, but proxies on the way may not: prefer a header to api_key in the query string.
Responses
A successful call answers HTTP 200 with status: "success" and the result in data. An error answers the HTTP status of the error with status: "error" and data.name, data.message and data.code.
- Amounts are decimal strings with all decimals of the currency, e.g.
"49.900000"for USDT on Tron. - Times (
expire_utc,created_at_utc…) are Unix seconds, UTC. - Invoice, deposit and withdrawal ids are 24 lowercase hex characters.
- Responses are never cached (
Cache-Control: no-store).
{
"status": "success",
"data": { "txn_id": "6564f9b0c8e2a1d4f7b3e901", "invoice_url": "https://torpayment.net/invoice/6564f9b0c8e2a1d4f7b3e901" }
}{
"status": "error",
"data": {
"name": "Unprocessable entity",
"message": "Invalid attribute value: {\"amount\":\"must be greater than zero\"}",
"code": 104
}
}Limits
- 600 requests per minute per client (an IPv4 address or an IPv6 /64), over the whole server. Above that: 429, code 112.
- 300 requests per minute per API key on this API, whatever address they come from — your shop's own budget, which no other shop can spend. Above that: 429, code 112.
- 120 new invoices per minute per shop (a customer switching the currency of an order does not count): 429, code 112.
- 10,000 orders waiting for payment (status
neworpending) per shop: 429, code 118. Shorterexpire_minfrees them sooner. - 30 currency switches per order on the checkout page (code 118).
- 120 new deposit addresses per minute per shop (code 112) and 10,000 in total per shop (code 118).
- 20 fee estimates per minute per API key; 100 recipients per withdrawal.
- Request bodies up to 256 KB.
Create an invoice
/api/v1/invoices/newCreates an invoice with its own payment address and returns the checkout link.Price the invoice either in fiat (source_amount + source_currency: the crypto amount is computed from the current rate) or directly in crypto (amount in currency). Send the customer to invoice_url: the hosted checkout shows the address, the exact amount, a QR code, a countdown and the live status. When the status changes your server gets a callback.
Parameters
| Parameter | Type | Description | |
|---|---|---|---|
order_number | string | required | Your order id, up to 255 characters. Unique per shop: a second invoice with the same number is refused (code 106). |
order_name | string | required | What is being paid for, up to 255 characters; shown to the customer. |
source_amount | decimal | optional | Price in fiat, e.g. 49.90. Needs source_currency. |
source_currency | string | optional | Fiat code of source_amount, e.g. USD, EUR. Needs source_amount. |
amount | decimal | optional | Price in crypto, in currency, with at most that currency’s decimals. Required when no source_amount is sent; when both are sent the fiat price is used. |
currency | string | optional | Currency id to pay in, e.g. USDT_TRX. When set, the checkout goes straight to the payment details.Default: the first of allowed_psys_cids, else the first currency the shop accepts; the customer then chooses on the checkout page. |
allowed_psys_cids | list | optional | Comma-separated currency ids the customer may choose from (up to 50). Each must have a wallet in the shop.Default: every currency the shop accepts. |
description | string | optional | Longer description, up to 2,000 characters. |
email | string | optional | The customer’s e-mail, stored with the invoice (searchable in the operations list). |
expire_min | integer | optional | Minutes the customer has to pay, 1–10,080.Default: the shop’s setting (60 unless you changed it). |
callback_url | URL | optional | Where the status callbacks of this invoice go. Add json=true to its query to receive JSON instead of form data.Default: the shop’s Status URL. |
success_callback_url | URL | optional | An extra callback when the invoice is paid (sent only if it differs from the status URL).Default: the shop’s Success URL. |
fail_callback_url | URL | optional | An extra callback when the invoice expires or ends in error (sent only if it differs from the status URL).Default: the shop’s Fail URL. |
success_invoice_url | URL | optional | Where the payer goes after paying: the checkout sends them there 5 seconds after the payment is confirmed (they can choose to stay), and its “Return to the store” button leads there. |
fail_invoice_url | URL | optional | “Back to the shop” link when the invoice expired, was cancelled or failed.Default: success_invoice_url. |
language | string | optional | Checkout language: en or ru. A ?lang= on the checkout link takes precedence. |
return_existing | boolean | optional | true: if the order number already has an invoice, return it instead of error 106. Safe for retries.Default: false |
redirect_to_invoice | boolean | optional | true: answer with a 302 redirect to the checkout page instead of JSON (for a browser form that posts straight here).Default: false |
plugin | string | optional | Name of your integration (up to 60 characters); stored with the invoice. |
version | string | optional | Version of your integration (up to 30 characters). |
- Callback URLs must be
httporhttpson a public address, on port 80, 443 or 1024 and up (ports of databases and node RPC are refused), without a user name or password, and not on this gateway itself. - A fiat-priced invoice can be paid in any allowed currency: when the customer switches, a new invoice of the same order is created with its own address, priced from the same fiat amount at the current rate. An invoice priced in crypto also gets a USD value when a rate is available and can then be switched the same way; without a rate it is fixed to its currency.
Example
curl -G "https://torpayment.net/api/v1/invoices/new" \
-H "X-Api-Key: YOUR_API_KEY" \
--data-urlencode "order_number=1001" \
--data-urlencode "order_name=Order 1001" \
--data-urlencode "source_amount=49.90" \
--data-urlencode "source_currency=USD" \
--data-urlencode "allowed_psys_cids=USDT_TRX,BTC,ETH" \
--data-urlencode "callback_url=https://shop.example/callback?json=true" \
--data-urlencode "success_invoice_url=https://shop.example/thanks"curl -X POST "https://torpayment.net/api/v1/invoices/new" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"order_number":"1002","order_name":"Order 1002","amount":"0.0005","currency":"BTC"}'Response
{
"status": "success",
"data": {
"txn_id": "6564f9b0c8e2a1d4f7b3e901",
"invoice_url": "https://torpayment.net/invoice/6564f9b0c8e2a1d4f7b3e901",
"amount": "49.900000",
"pending_amount": "49.900000",
"wallet_hash": "TQ8mY4kq2Vn3cP7rLw9hXe5bJd6Fs1v3Kp",
"psys_cid": "USDT_TRX",
"currency": "USDT",
"status": "new",
"source_currency": "USD",
"source_rate": "1.000000",
"expire_utc": 1763393400,
"expected_confirmations": "20",
"qr_code": "data:image/png;base64,iVBORw0KGgo…",
"invoice_commission": "0.000000",
"invoice_sum": "49.900000",
"invoice_total_sum": "49.900000",
"verify_hash": "9b0f3c1e5a7d2b8c4e6f1a3d5c7e9b0a2c4e6f81"
}
}| Field | Type | Meaning |
|---|---|---|
txn_id | string | Invoice id. |
invoice_url | string | The checkout page to send the customer to. |
amount | decimal | Amount due, in currency. |
pending_amount | decimal | Amount still missing (the whole amount for a new invoice). |
wallet_hash | string | The address to pay to, unique to this invoice. |
psys_cid | string | Currency id of the invoice. |
currency | string | Currency code (the same as the id except for a few legacy assets, e.g. ZEC for TZEC). |
status | string | Invoice status. |
source_currency | string | Fiat of the price (also USD for a crypto-priced invoice when a rate was available), else empty. |
source_rate | decimal | Units of currency per 1 unit of source_currency, else empty. |
expire_utc | integer | When the invoice expires (Unix seconds). |
expected_confirmations | string | Confirmations a payment needs on this network. |
qr_code | string | QR code of the payment request as a data:image/png;base64 URI. |
invoice_commission | decimal | Always zero: the gateway takes no commission. |
invoice_sum, invoice_total_sum | decimal | Amount due (the same as amount). |
verify_hash | string | HMAC-SHA1 of the JSON of data without this field, keyed with your API key. |
Invoice statuses
Only the gateway changes a status, from what it sees on the blockchain. Final statuses (completed, mismatch, cancelled, cancelled duplicate, error) do not change back by themselves; expired can still become completed when the operator accepts a late payment. Deliver only on completed or mismatch, and check the amount and currency in the callback.
| Status | When | What your shop does |
|---|---|---|
| new | Created; nothing has arrived yet. | Wait. |
| pending | A payment was seen but is not enough yet: it is still unconfirmed, or the confirmed amount is short of the price. | Do not deliver yet. You may show “payment received, confirming”. |
| completed | Paid: confirmed funds that arrived in time cover the price (less the underpayment tolerance set for the shop). | Deliver the order. |
| mismatch | Paid with more than the price, when the shop is set to mark overpayments this way (by default an overpaid invoice is completed). | Deliver the order; decide what to do with the excess. |
| expired | Time ran out (expiry plus the shop’s grace period) without enough money. Possibly partly paid: see amount. An invoice with enough money on its way is not expired while it confirms. | Do not deliver. If money arrived, settle with the customer. A full payment that arrives after expiry is reported to the operator, who can accept it: the invoice then becomes completed and you get a callback. |
| cancelled | Expired with nothing received, 10 hours after it was created. | Nothing to do; the order was not paid. |
| cancelled duplicate | The customer switched to another currency and paid that invoice of the same order; this one was closed. | Ignore it: the paid invoice of the order arrives with its own callback. |
| error | Was paid, but the confirmed funds were later reverted on the blockchain (a deep reorganisation). | Treat the payment as not received; if you delivered, contact the customer. |
Invoices, operations, balances
Read-only endpoints. Every one needs the API key and sees only the shop the key belongs to.
Get an invoice
/api/v1/invoices/:idOne invoice in detail: data.invoice is an operation object (fields below).curl -H "X-Api-Key: YOUR_API_KEY" "https://torpayment.net/api/v1/invoices/6564f9b0c8e2a1d4f7b3e901"| Field | Type | Meaning |
|---|---|---|
id | string | Operation id (for an invoice: the invoice id). |
type | string | invoice, cash_in (a top-up of a deposit address), cash_out or mass_cash_out (withdrawals). |
status | string | Status of the operation; for invoices see statuses. |
status_code | integer | 3 when the operation is completed (absent otherwise). |
psys_cid, currency | string | Currency id and code. |
sum | decimal | Invoice: amount due. Deposit and withdrawal: the amount. |
amount | decimal | Invoice: everything received so far, confirmed or not. |
pending_sum | decimal | Invoice: received but not yet confirmed. Withdrawal: not yet completed. |
actual_sum, actual_invoice_sum | decimal | Invoice: confirmed amount. |
commission, actual_commission, actual_fee | decimal | Always zero for invoices: no commission. |
source_currency, source_rate | string | As in the invoice response. |
wallet_hash | string | The payment address (withdrawal: the recipient, or the hot wallet for a batch). |
params | object | Invoice: order_number, order_name, description, source_amount, source_currency, source_rate, currency, amount. Deposit: deposit_uid, currency, amount. |
tx_id, tx_url | array | Blockchain transaction ids and their explorer links. |
confirmations | integer | Confirmations of the least confirmed payment. |
created_at_utc, expire_at_utc | integer | Unix seconds (expire_at_utc is null for deposits and withdrawals). |
parent_id | string | Present when the invoice is a currency switch: the id of the order’s first invoice. |
child_ids | array | Detail view of an order’s first invoice: ids of its currency switches. |
finished_at_utc | integer | Detail view: when the invoice was paid (or null). |
invoice_url | string | Detail view: the checkout page. |
shop_id | string | Your shop id. |
user_id | integer | Always 1 (kept for compatibility). |
List operations
/api/v1/operationsInvoices, deposit top-ups and withdrawals of the shop, newest first.| Parameter | Type | Description | |
|---|---|---|---|
page | integer | optional | Page number, from 1.Default: 1 |
limit | integer | optional | Items per page, 1–100 (per-page is accepted too).Default: 10 |
type | string | optional | invoice, cash_in, cash_out or mass_cash_out. |
status | string | optional | Only operations in this status. |
currency | string | optional | Only this currency id. |
search | string | optional | Exact match (case-insensitive) on the id, the order number, the customer e-mail or a transaction id; for deposits also the customer uid, for withdrawals a recipient address. |
data.operations is the list (invoices here come without the detail-only fields). data._meta has totalCount, pageCount, currentPage and perPage; data._links has self, first, last and, if there is one, next.
/api/v1/operations/:idOne operation by id: an invoice (in detail), a deposit top-up or a withdrawal. data is the operation object itself.Currencies and rates
/api/v1/currenciesEvery currency of the gateway with its rate in USD./api/v1/currencies/:fiatThe same with rates in another fiat, e.g. /api/v1/currencies/EUR.| Field | Type | Meaning |
|---|---|---|
cid | string | Currency id. |
currency, name | string | Code and name. |
icon | string | URL of the coin icon on this gateway. |
precision | string | Decimals of the currency. |
min_sum_in | decimal | Smallest invoice amount. |
hidden | integer | 0: your shop can accept it now; 1: it cannot (no wallet, or not enabled for the shop). |
maintenance | boolean | true when there is no fresh rate: then it cannot be used for fiat-priced invoices. |
price_usd | decimal | USD price of one coin. |
rate_usd, fiat_rate | decimal | Coins per 1 USD, and per 1 unit of the requested fiat. |
fiat | string | The fiat of fiat_rate. |
invoice_commission_percentage | string | Always "0". |
Balances
/api/v1/balances/:psys_ciddata = { psys_cid, currency, balance } for one currency id.- With a managed wallet on that network: the balance of the shop’s hot wallet, as last read from the blockchain.
- With your own wallet: the confirmed payments this gateway has seen arrive and has not moved itself. The real balance is in your wallet.
Callbacks
The gateway tells your server about changes with an HTTP POST — a callback. Treat it as a signal: verify its signature, then act on its status. You can always read the current state with Get an invoice.
When they are sent
- Status callback — to the invoice’s
callback_url, else the shop’s Status URL — whenever the status or the received amounts change (a new confirmation alone does not send one). - Success callback — to
success_callback_url, else the shop’s Success URL — when the invoice becomescompletedormismatch, if that URL differs from the status URL. - Fail callback — to
fail_callback_url, else the shop’s Fail URL — when the invoice becomesexpiredorerror, if that URL differs from the status URL. - Deposit top-ups and withdrawals send their callbacks to the shop’s Status URL (top-ups also to its Success URL); see deposits and withdrawals.
Form or JSON. By default the body is multipart/form-data (arrays such as tx_urls are JSON strings inside it). If the callback URL has json=true in its query string (e.g. https://shop.example/callback?json=true), the body is application/json.
POST /callback?json=true HTTP/1.1
Content-Type: application/json
User-Agent: TorPayment-Webhooks/1.0
X-TorPayment-Event-Id: 18342
X-TorPayment-Signature: t=1763390731,v1=5d0c…e19a
{
"txn_id": "6564f9b0c8e2a1d4f7b3e901",
"ipn_type": "invoice",
"merchant": "Northwind Store",
"merchant_id": "6564f2a7c8e2a1d4f7b3e1aa",
"amount": "49.900000",
"seen_amount": "49.900000",
"currency": "USDT",
"order_number": "1001",
"order_name": "Order 1001",
"confirmations": "20",
"status": "completed",
"source_currency": "USD",
"source_amount": "49.90",
"source_rate": "1.000000",
"comment": "Invoice details: https://torpayment.net/invoice/6564f9b0c8e2a1d4f7b3e901",
"invoice_commission": "0.000000",
"invoice_sum": "49.900000",
"invoice_total_sum": "49.900000",
"psys_cid": "USDT_TRX",
"pending_amount": "0.000000",
"confirmed_amount": "49.900000",
"wallet_hash": "TQ8mY4kq2Vn3cP7rLw9hXe5bJd6Fs1v3Kp",
"qr_code": "data:image/png;base64,iVBORw0KGgo…",
"tx_urls": ["https://tronscan.org/#/transaction/7c1e…"],
"expire_utc": 1763393400,
"verify_hash": "2f9a…41c7"
}Invoice callback fields
| Field | Type | Meaning |
|---|---|---|
txn_id | string | Invoice id. |
ipn_type | string | invoice (deposits: pay_in; withdrawals: cash_out / mass_cash_out). |
merchant, merchant_id | string | Shop name and shop id. |
order_number, order_name | string | As sent when the invoice was created. |
status | string | Invoice status. |
amount | decimal | While the invoice is open: everything received so far, confirmed or not. Once it is paid (completed, mismatch): confirmed money only, so it is safe to credit. A transfer that arrives after that sends the callback again with a higher amount: handle each event id once. |
seen_amount | decimal | Everything received so far, confirmed or not, in every status. |
confirmed_amount | decimal | Confirmed money only, in every status. |
pending_amount | decimal | Still missing to the full price (never negative). |
invoice_sum, invoice_total_sum | decimal | Amount due. |
invoice_commission | decimal | Always zero. |
currency, psys_cid | string | Currency code and id. |
source_currency, source_amount, source_rate | string | The fiat price, if any (empty strings otherwise). |
confirmations | string | Confirmations of the least confirmed payment. |
wallet_hash | string | The invoice address. |
tx_urls | array | Explorer links of the payments (a JSON string in form mode). |
qr_code | string | QR code as a data URI. |
expire_utc | integer | Expiry, Unix seconds. |
comment | string | A line with the checkout link. |
switch_id | string | Only for an invoice created by a currency switch: the id of the order’s first invoice. |
verify_hash | string | The signature, see below. |
Verifying a callback
Every callback is signed twice with your API key. Checking either one is enough; verify_hash works with existing integrations, the header adds a timestamp.
verify_hash, JSON mode: HMAC-SHA1 (hex) ofJSON.stringifyof the received object withoutverify_hash, keys in the order received, no spaces.verify_hash, form mode: HMAC-SHA1 (hex) of PHPserialize()of all fields exceptverify_hash, sorted by name (ksort). Every value is a string; lengths count UTF-8 bytes.- Header
X-TorPayment-Signature: t=<unix seconds>,v1=<hex>:v1is HMAC-SHA256 of<t>.<canonical>, where canonical is the raw request body in JSON mode, and the sameserialize()string as above in form mode. Reject callbacks whosetis more than 5 minutes from your clock.
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.SHOP_API_KEY; // the shop's API key
function safeEqual(a, b) {
const x = Buffer.from(String(a));
const y = Buffer.from(String(b));
return x.length === y.length && crypto.timingSafeEqual(x, y);
}
// JSON mode (the callback URL contains json=true): body = the parsed JSON object.
function verifyJson(body, secret) {
if (!body || typeof body.verify_hash !== 'string') return false;
const { verify_hash, ...data } = body;
const expected = crypto.createHmac('sha1', secret).update(JSON.stringify(data)).digest('hex');
return safeEqual(expected, verify_hash);
}
// Form mode (default): fields = the multipart/form-data fields as strings
// (e.g. parsed with multer or busboy).
function serializeFields(fields) {
const keys = Object.keys(fields)
.filter((k) => k !== 'verify_hash')
.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
let s = `a:${keys.length}:{`;
for (const k of keys) {
const v = String(fields[k]);
s += `s:${Buffer.byteLength(k)}:"${k}";s:${Buffer.byteLength(v)}:"${v}";`;
}
return s + '}';
}
function verifyForm(fields, secret) {
if (typeof fields.verify_hash !== 'string') return false;
const expected = crypto.createHmac('sha1', secret).update(serializeFields(fields)).digest('hex');
return safeEqual(expected, fields.verify_hash);
}
// Optional: the X-TorPayment-Signature header. canonical = the raw body (JSON mode)
// or serializeFields(fields) (form mode).
function verifyHeader(header, canonical, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${canonical}`).digest('hex');
return safeEqual(expected, m[2]);
}
const app = express();
app.post('/callback', express.json(), (req, res) => {
if (!verifyJson(req.body, SECRET)) return res.status(403).send('bad signature');
const { order_number, status, amount, psys_cid } = req.body;
if (status === 'completed' || status === 'mismatch') {
// mark the order paid once (see X-TorPayment-Event-Id), after checking amount and psys_cid
}
res.status(200).send('OK');
});
app.listen(3000);<?php
// Form mode (default): the fields arrive in $_POST.
function verify_callback(array $post, string $secretKey): bool {
if (!isset($post['verify_hash']) || !is_string($post['verify_hash'])) return false;
$given = $post['verify_hash'];
unset($post['verify_hash']);
ksort($post);
if (isset($post['tx_urls'])) $post['tx_urls'] = html_entity_decode($post['tx_urls']);
$expected = hash_hmac('sha1', serialize($post), $secretKey);
return hash_equals($expected, $given);
}
// JSON mode (json=true in the callback URL).
function verify_callback_json(string $rawBody, string $secretKey): bool {
$data = json_decode($rawBody, true);
if (!is_array($data) || !isset($data['verify_hash'])) return false;
$given = (string) $data['verify_hash'];
unset($data['verify_hash']);
$json = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_LINE_TERMINATORS);
return hash_equals(hash_hmac('sha1', $json, $secretKey), $given);
}
$secretKey = getenv('SHOP_API_KEY');
if (!verify_callback($_POST, $secretKey)) {
http_response_code(403);
exit('bad signature');
}
if ($_POST['status'] === 'completed' || $_POST['status'] === 'mismatch') {
// mark the order $_POST['order_number'] paid once, after checking the amount and psys_cid
}
http_response_code(200);
echo 'OK';import hashlib, hmac, json, time
def _serialize(fields):
"""PHP serialize() of a dict of str -> str, keys sorted by their UTF-8 bytes."""
keys = sorted(fields, key=lambda k: k.encode('utf-8'))
out = 'a:%d:{' % len(keys)
for k in keys:
v = fields[k]
out += 's:%d:"%s";s:%d:"%s";' % (len(k.encode('utf-8')), k, len(v.encode('utf-8')), v)
return out + '}'
def verify_form(form, secret):
"""Form mode: form = the multipart fields (Flask: request.form.to_dict())."""
fields = dict(form)
given = fields.pop('verify_hash', None)
if not isinstance(given, str):
return False
digest = hmac.new(secret.encode(), _serialize(fields).encode('utf-8'), hashlib.sha1).hexdigest()
return hmac.compare_digest(digest, given)
def verify_json(raw_body, secret):
"""JSON mode: raw_body = the request body as text."""
data = json.loads(raw_body)
given = data.pop('verify_hash', None)
if not isinstance(given, str):
return False
canonical = json.dumps(data, separators=(',', ':'), ensure_ascii=False)
digest = hmac.new(secret.encode(), canonical.encode('utf-8'), hashlib.sha1).hexdigest()
return hmac.compare_digest(digest, given)
def verify_header(header, canonical, secret, max_age=300):
"""X-TorPayment-Signature; canonical = raw body (JSON) or _serialize(fields) (form)."""
try:
parts = dict(item.split('=', 1) for item in (header or '').split(','))
t, v1 = parts['t'], parts['v1']
except (KeyError, ValueError):
return False
if not t.isdigit() or abs(time.time() - int(t)) > max_age:
return False
digest = hmac.new(secret.encode(), f'{t}.{canonical}'.encode('utf-8'), hashlib.sha256).hexdigest()
return hmac.compare_digest(digest, v1)In form mode the value of tx_urls never contains an HTML entity (an & that would start one is sent as the JSON escape \u0026), so PHP’s html_entity_decode changes nothing and the other languages skip that step.
Answer, retries and idempotency
- Answer with any 2xx status within 10 seconds. Anything else — another status, a redirect (redirects are not followed), a timeout, a refused connection — is a failed attempt. A host that times out several times in a row gets a shorter timeout and fewer parallel deliveries until it answers again, so answer quickly and do slow work afterwards. The beginning of your answer is shown in the panel’s Callbacks page.
- A failed callback is retried after 15 s, 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h, 24 h, 24 h: 12 attempts over about 94 hours, then it is marked failed. You can resend it by hand from the panel’s Callbacks page.
X-TorPayment-Event-Ididentifies one callback and stays the same on every retry and manual resend: store it and process each id once. The body (andverify_hash) of a retry is the same as the first attempt; onlytin the signature header is new.- Callbacks of one invoice to one URL arrive in order: the next one waits until the previous one is delivered or given up. Still, update an order only forward (a paid order stays paid).
- If a shop already has 5,000 undelivered callbacks, new callbacks that only say an unpaid invoice expired or was cancelled are not queued (they are listed as failed in the panel). Callbacks about money are always queued.
Permanent deposit addresses
Give a customer an address of their own that stays the same forever, e.g. to top up an account balance. One customer uid gets one address per network; every currency of that network arrives at the same address (USDT and USDC on Ethereum share it). Each top-up is reported with a callback when it is confirmed.
/api/v1/shops/deposit/newReturns the customer’s address, creating it on the first call.| Parameter | Type | Description | |
|---|---|---|---|
uid | string | required | Your id of the customer, up to 255 characters. |
psys_cid | list | required | Currency id, or several separated by commas (up to 50). |
{
"status": "success",
"data": { "uid": "customer-42", "hash": "TJx2Lq5w8Hc3VbN6kq7r8LqP4sZt1yUe9D", "psys_cid": "USDT_TRX" }
}data is one object for one currency, or an array of such objects when psys_cid lists several. hash is the address. Errors: 105 for an unknown currency, 110 when it is not enabled for the shop or has no wallet, 112 / 118 for the limits.
/api/v1/shops/depositDeposit addresses of the shop, newest first: an array of { uid, hash, psys_cid }, one entry per currency of each address’s network.| Parameter | Type | Description | |
|---|---|---|---|
uid | string | optional | Only this customer. |
psys_cid | list | optional | Only these currencies. |
page | integer | optional | Page number, from 1.Default: 1 |
limit | integer | optional | Items per page, 1–100.Default: 20 |
Top-ups are operations of type cash_in (List operations). Their callback goes to the shop’s Status URL (and its Success URL, if different) with ipn_type: "pay_in" and status: "completed" once the top-up is confirmed. If a top-up you were told about is later reverted on the blockchain, a second callback says status: "error".
| Field | Type | Meaning |
|---|---|---|
txn_id | string | Id of the top-up. |
deposit_uid | string | The customer uid. |
amount, deposit_sum, invoice_sum, invoice_total_sum | decimal | The amount received. |
currency, psys_cid | string | Currency code and id. |
status | string | completed, or error for a reverted top-up. |
confirmations | string | Confirmations of the transaction. |
wallet_hash, tx_urls, qr_code | string / array | The deposit address, the explorer link, a QR code of the address. |
source_currency, source_rate, source_amount | string | USD value at the time of confirmation, when a rate was available. |
merchant, merchant_id, pending_amount, invoice_commission, comment | string | As in invoice callbacks (pending_amount and the commission are zero). |
verify_hash | string | Signed exactly like invoice callbacks. |
Withdrawals
Withdrawals leave from the shop’s managed hot wallet, so they exist only on networks where the shop has a managed wallet, and only when the gateway runs its signer. They are off for the API until you switch them on for the shop in the panel. With manual approval (the default) a withdrawal created here waits in status new until someone approves it in the panel.
/api/v1/operations/withdrawCreates a withdrawal to one address (cash_out) or to several (mass_cash_out).| Parameter | Type | Description | |
|---|---|---|---|
currency | string | required | Currency id to send (psys_cid is accepted too). |
to | list | required | Recipient address, or several separated by commas (up to 100, each at most once, not the hot wallet itself). |
amount | list | required | Amount for each address in the same order, comma-separated; each at least the currency’s minimum. |
type | string | optional | cash_out (exactly one address) or mass_cash_out (several).Default: cash_out |
feePlan | string | optional | Network fee level: normal or priority (fee_plan is accepted too).Default: normal |
idempotency_key | string | optional | Up to 100 characters, or the Idempotency-Key header. Repeating a request with the same key returns the withdrawal already created; the same key with different addresses or amounts is refused (409, code 113). |
curl -X POST "https://torpayment.net/api/v1/operations/withdraw" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Idempotency-Key: payout-2026-11-17-001" \
--data-urlencode "currency=USDT_TRX" \
--data-urlencode "type=mass_cash_out" \
--data-urlencode "to=TFc4Wb2Lr9Nq8mQ2ZyHd5Kp3Vt7Xs1Ce6A,TRk9Pz4Ya7Vd1a1Pw7DmQ6Lc8Nf2Hs5Tb3" \
--data-urlencode "amount=80,60"The amounts and the estimated network fees are reserved from the hot wallet’s balance when the withdrawal is created, so two withdrawals never promise the same coins; fees are paid in the network’s native coin. data is the withdrawal as an operation: id, type, status, psys_cid, currency, amount (total), fee and fee_currency (estimated, then actual), sendmany ({ address: amount }), params.fee.plan, tx_id, tx_url, created_at_utc, finished_at_utc and error when there is one.
new— waiting for approval in the panel;approved— approved, waiting to start;processing— being sent, one recipient after another;completed— every transfer confirmed;error— at least one transfer failed (seeerror);cancelled— cancelled in the panel before anything was sent.
Every status change sends a callback to the shop’s Status URL with ipn_type cash_out or mass_cash_out, signed like the others.
/api/v1/operations/fee/:psys_cidEstimates the network fee of a withdrawal. data = { fee, currency, psys_cid, plan } — the total, in the native coin.| Parameter | Type | Description | |
|---|---|---|---|
addresses | list | required | Recipient addresses, comma-separated. |
amounts | list | required | One amount per address. |
feePlan | string | optional | normal or priority.Default: normal |
At most 20 requests per minute per API key. The first 20 recipients are quoted by the network; each further one is counted at the highest of those fees.
/api/v1/operations/fee-plan/:psys_cidThe current fee of one minimal withdrawal under each plan: data = { psys_cid, currency, normal: { value, currency }, priority: { value, currency } }.Errors you may get here: 103 / 104 for missing or invalid parameters (an invalid address, more amounts than addresses, cash_out with several addresses), 105 unknown currency, 107 an amount below the minimum, 115 the fee cannot be estimated, 116 not enough balance, 117 withdrawals disabled or no managed wallet, 102 the shop is disabled or withdrawals are stopped, 113 idempotency key conflict.
Payment links
A payment link is a product with a price that you create in the panel. Its public address https://torpayment.net/pay/<slug> shows the product and asks the buyer for an e-mail address; each time one is given, a new invoice is created and the buyer goes on to its checkout to choose the currency. One link can be posted anywhere and paid by any number of buyers, each with an invoice and an address of their own. Looking at the link creates nothing. No API call is needed.
Optional query parameters:
ref— your reference of the buyer (letters, digits and_ . : @ -, up to 64). It comes back in the callback’sorder_numberas<slug>-<ref>-<random>; without it the order number is<slug>-<random>.email— the buyer’s e-mail, when you already know it: the question is skipped and the invoice is created at once with the address stored in it.lang— checkout language,enorru.
A value that does not fit is ignored rather than refused, so the link always opens. The buyer’s e-mail is kept with the invoice: the panel shows it on the invoice’s page. Callbacks go to the shop’s URLs like for any invoice.
https://torpayment.net/pay/premium-plan?ref=user-1842&lang=enErrors
Every error answers with its HTTP status and {"status":"error","data":{"name","message","code"}}. Use code in your program and show or log message. A body that cannot be parsed or is too large answers 400 or 413 with code 104; an unknown /api/ path answers 404 with code 111.
| Code | HTTP | Name | Meaning |
|---|---|---|---|
| 101 | 401 | Unauthorized | The API key is missing or wrong, or the shop or its account is disabled. |
| 102 | 403 | Forbidden | The request is not allowed: the IP address is not in the shop’s allowlist, the shop is disabled, or withdrawals are stopped. |
| 103 | 400 | Bad Request | A required parameter is missing; the message names it. |
| 104 | 422 | Unprocessable entity | A parameter has an invalid value; the message names it and says why. |
| 105 | 422 | Unprocessable entity | Unknown currency id. |
| 106 | 422 | Unprocessable entity | An invoice with this order_number already exists in this shop (send return_existing=true to get it back instead). |
| 107 | 422 | Unprocessable entity | The amount is below the currency’s minimum. |
| 108 | 500 | Internal Server Error | An unexpected error on the gateway’s side. Retry later. |
| 109 | 503 | Service Unavailable | No fresh exchange rate for this currency or fiat right now. Retry later or price the invoice in crypto. |
| 110 | 422 | Unprocessable entity | The shop has no receiving wallet for this currency (or the currency is not enabled for the shop). |
| 111 | 404 | Not Found | The invoice, operation or route does not exist (or belongs to another shop). |
| 112 | 429 | Too Many Requests | A per-minute limit was reached. Wait and retry. |
| 113 | 409 | Conflict | The request conflicts with the current state, e.g. an idempotency key reused for a different withdrawal, or no free address left in a wallet’s pool of prepared addresses. |
| 115 | 400 | Bad Request | The network fee cannot be estimated (often: the balance cannot cover it, or cannot be read right now). |
| 116 | 422 | Unprocessable entity | The hot wallet balance is not enough for the withdrawal and its network fee. |
| 117 | 403 | Forbidden | Withdrawals are not possible: they are disabled for API use, or there is no managed wallet on that network. |
| 118 | 429 | Too Many Requests | A standing quota is used up (open invoices, deposit addresses, currency switches of one order). |
| 124 | 402 | Payment Required | The account’s one-time access fee has not been paid yet. |
Currency ids
Use these ids in currency, allowed_psys_cids and psys_cid (case does not matter). Note that a token without a suffix is the Ethereum one: USDT is Tether ERC-20, Tether on Tron is USDT_TRX. TON is accepted for GRAM. Your shop can accept a currency only when it has a wallet on its network — see hidden in Currencies.
| Id | Coin | Name | Network |
|---|---|---|---|
BTC | BTC | Bitcoin | Bitcoin |
LTC | LTC | Litecoin | Litecoin |
DOGE | DOGE | Dogecoin | Dogecoin |
TZEC | ZEC | Zcash | Zcash |
ETH | ETH | Ethereum | Ethereum |
USDT | USDT | Tether ERC-20 | Ethereum |
USDC | USDC | USD Coin ERC-20 | Ethereum |
USDC_BASE | USDC | USD Coin (Base) | Base |
BNB | BNB | BNB | BNB Smart Chain |
USDT_BSC | USDT | Tether BEP-20 | BNB Smart Chain |
USDC_BSC | USDC | USD Coin BEP-20 | BNB Smart Chain |
TRX | TRX | Tron | Tron |
USDT_TRX | USDT | Tether TRC-20 | Tron |
XMR | XMR | Monero | Monero |
SOL | SOL | Solana | Solana |
USDT_SOL | USDT | Tether (Solana) | Solana |
USDC_SOL | USDC | USD Coin (Solana) | Solana |
GRAM | GRAM | Gram (TON) | TON |
USDT_TON | USDT | Tether (TON) | TON |