Crypto payment gateway

Developers

TorPayment API documentation

Create invoices, receive signed callbacks, give customers permanent deposit addresses and send withdrawals — with plain HTTPS requests from any language.

Base URLhttps://torpayment.net/api/v1API keys in the panel

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.

  1. Create a shop in the merchant panel and copy its API key.
  2. Connect a wallet for every network you want to be paid in. A currency without a wallet cannot be used (error 110).
  3. Send requests to the base URL below and handle the callbacks your server receives.
Base URLhttps://torpayment.net/api/v1

Authentication

Every request carries the shop’s API key, in one of three ways (checked in this order):

  • the api_key parameter, 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).
Success200
{
  "status": "success",
  "data": { "txn_id": "6564f9b0c8e2a1d4f7b3e901", "invoice_url": "https://torpayment.net/invoice/6564f9b0c8e2a1d4f7b3e901" }
}
Error422
{
  "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 new or pending) per shop: 429, code 118. Shorter expire_min frees 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

GETPOST/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

ParameterTypeDescription
order_numberstringrequiredYour order id, up to 255 characters. Unique per shop: a second invoice with the same number is refused (code 106).
order_namestringrequiredWhat is being paid for, up to 255 characters; shown to the customer.
source_amountdecimaloptionalPrice in fiat, e.g. 49.90. Needs source_currency.
source_currencystringoptionalFiat code of source_amount, e.g. USD, EUR. Needs source_amount.
amountdecimaloptionalPrice 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.
currencystringoptionalCurrency 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_cidslistoptionalComma-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.
descriptionstringoptionalLonger description, up to 2,000 characters.
emailstringoptionalThe customer’s e-mail, stored with the invoice (searchable in the operations list).
expire_minintegeroptionalMinutes the customer has to pay, 1–10,080.Default: the shop’s setting (60 unless you changed it).
callback_urlURLoptionalWhere 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_urlURLoptionalAn extra callback when the invoice is paid (sent only if it differs from the status URL).Default: the shop’s Success URL.
fail_callback_urlURLoptionalAn 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_urlURLoptionalWhere 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_urlURLoptional“Back to the shop” link when the invoice expired, was cancelled or failed.Default: success_invoice_url.
languagestringoptionalCheckout language: en or ru. A ?lang= on the checkout link takes precedence.
return_existingbooleanoptionaltrue: if the order number already has an invoice, return it instead of error 106. Safe for retries.Default: false
redirect_to_invoicebooleanoptionaltrue: answer with a 302 redirect to the checkout page instead of JSON (for a browser form that posts straight here).Default: false
pluginstringoptionalName of your integration (up to 60 characters); stored with the invoice.
versionstringoptionalVersion of your integration (up to 30 characters).
  • Callback URLs must be http or https on 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
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, JSON body
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

Response200
{
  "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"
  }
}
FieldTypeMeaning
txn_idstringInvoice id.
invoice_urlstringThe checkout page to send the customer to.
amountdecimalAmount due, in currency.
pending_amountdecimalAmount still missing (the whole amount for a new invoice).
wallet_hashstringThe address to pay to, unique to this invoice.
psys_cidstringCurrency id of the invoice.
currencystringCurrency code (the same as the id except for a few legacy assets, e.g. ZEC for TZEC).
statusstringInvoice status.
source_currencystringFiat of the price (also USD for a crypto-priced invoice when a rate was available), else empty.
source_ratedecimalUnits of currency per 1 unit of source_currency, else empty.
expire_utcintegerWhen the invoice expires (Unix seconds).
expected_confirmationsstringConfirmations a payment needs on this network.
qr_codestringQR code of the payment request as a data:image/png;base64 URI.
invoice_commissiondecimalAlways zero: the gateway takes no commission.
invoice_sum, invoice_total_sumdecimalAmount due (the same as amount).
verify_hashstringHMAC-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.

StatusWhenWhat your shop does
newCreated; nothing has arrived yet.Wait.
pendingA 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”.
completedPaid: confirmed funds that arrived in time cover the price (less the underpayment tolerance set for the shop).Deliver the order.
mismatchPaid 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.
expiredTime 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.
cancelledExpired with nothing received, 10 hours after it was created.Nothing to do; the order was not paid.
cancelled duplicateThe 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.
errorWas 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

GET/api/v1/invoices/:idOne invoice in detail: data.invoice is an operation object (fields below).
curl
curl -H "X-Api-Key: YOUR_API_KEY" "https://torpayment.net/api/v1/invoices/6564f9b0c8e2a1d4f7b3e901"
FieldTypeMeaning
idstringOperation id (for an invoice: the invoice id).
typestringinvoice, cash_in (a top-up of a deposit address), cash_out or mass_cash_out (withdrawals).
statusstringStatus of the operation; for invoices see statuses.
status_codeinteger3 when the operation is completed (absent otherwise).
psys_cid, currencystringCurrency id and code.
sumdecimalInvoice: amount due. Deposit and withdrawal: the amount.
amountdecimalInvoice: everything received so far, confirmed or not.
pending_sumdecimalInvoice: received but not yet confirmed. Withdrawal: not yet completed.
actual_sum, actual_invoice_sumdecimalInvoice: confirmed amount.
commission, actual_commission, actual_feedecimalAlways zero for invoices: no commission.
source_currency, source_ratestringAs in the invoice response.
wallet_hashstringThe payment address (withdrawal: the recipient, or the hot wallet for a batch).
paramsobjectInvoice: order_number, order_name, description, source_amount, source_currency, source_rate, currency, amount. Deposit: deposit_uid, currency, amount.
tx_id, tx_urlarrayBlockchain transaction ids and their explorer links.
confirmationsintegerConfirmations of the least confirmed payment.
created_at_utc, expire_at_utcintegerUnix seconds (expire_at_utc is null for deposits and withdrawals).
parent_idstringPresent when the invoice is a currency switch: the id of the order’s first invoice.
child_idsarrayDetail view of an order’s first invoice: ids of its currency switches.
finished_at_utcintegerDetail view: when the invoice was paid (or null).
invoice_urlstringDetail view: the checkout page.
shop_idstringYour shop id.
user_idintegerAlways 1 (kept for compatibility).

List operations

GET/api/v1/operationsInvoices, deposit top-ups and withdrawals of the shop, newest first.
ParameterTypeDescription
pageintegeroptionalPage number, from 1.Default: 1
limitintegeroptionalItems per page, 1–100 (per-page is accepted too).Default: 10
typestringoptionalinvoice, cash_in, cash_out or mass_cash_out.
statusstringoptionalOnly operations in this status.
currencystringoptionalOnly this currency id.
searchstringoptionalExact 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.

GET/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

GET/api/v1/currenciesEvery currency of the gateway with its rate in USD.
GET/api/v1/currencies/:fiatThe same with rates in another fiat, e.g. /api/v1/currencies/EUR.
FieldTypeMeaning
cidstringCurrency id.
currency, namestringCode and name.
iconstringURL of the coin icon on this gateway.
precisionstringDecimals of the currency.
min_sum_indecimalSmallest invoice amount.
hiddeninteger0: your shop can accept it now; 1: it cannot (no wallet, or not enabled for the shop).
maintenancebooleantrue when there is no fresh rate: then it cannot be used for fiat-priced invoices.
price_usddecimalUSD price of one coin.
rate_usd, fiat_ratedecimalCoins per 1 USD, and per 1 unit of the requested fiat.
fiatstringThe fiat of fiat_rate.
invoice_commission_percentagestringAlways "0".

Balances

GET/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 becomes completed or mismatch, if that URL differs from the status URL.
  • Fail callback — to fail_callback_url, else the shop’s Fail URL — when the invoice becomes expired or error, 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.

Invoice callback (JSON mode)
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

FieldTypeMeaning
txn_idstringInvoice id.
ipn_typestringinvoice (deposits: pay_in; withdrawals: cash_out / mass_cash_out).
merchant, merchant_idstringShop name and shop id.
order_number, order_namestringAs sent when the invoice was created.
statusstringInvoice status.
amountdecimalWhile 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_amountdecimalEverything received so far, confirmed or not, in every status.
confirmed_amountdecimalConfirmed money only, in every status.
pending_amountdecimalStill missing to the full price (never negative).
invoice_sum, invoice_total_sumdecimalAmount due.
invoice_commissiondecimalAlways zero.
currency, psys_cidstringCurrency code and id.
source_currency, source_amount, source_ratestringThe fiat price, if any (empty strings otherwise).
confirmationsstringConfirmations of the least confirmed payment.
wallet_hashstringThe invoice address.
tx_urlsarrayExplorer links of the payments (a JSON string in form mode).
qr_codestringQR code as a data URI.
expire_utcintegerExpiry, Unix seconds.
commentstringA line with the checkout link.
switch_idstringOnly for an invoice created by a currency switch: the id of the order’s first invoice.
verify_hashstringThe 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) of JSON.stringify of the received object without verify_hash, keys in the order received, no spaces.
  • verify_hash, form mode: HMAC-SHA1 (hex) of PHP serialize() of all fields except verify_hash, sorted by name (ksort). Every value is a string; lengths count UTF-8 bytes.
  • Header X-TorPayment-Signature: t=<unix seconds>,v1=<hex>: v1 is HMAC-SHA256 of <t>.<canonical>, where canonical is the raw request body in JSON mode, and the same serialize() string as above in form mode. Reject callbacks whose t is more than 5 minutes from your clock.
Node.js
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
<?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';
Python
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-Id identifies one callback and stays the same on every retry and manual resend: store it and process each id once. The body (and verify_hash) of a retry is the same as the first attempt; only t in 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.

GETPOST/api/v1/shops/deposit/newReturns the customer’s address, creating it on the first call.
ParameterTypeDescription
uidstringrequiredYour id of the customer, up to 255 characters.
psys_cidlistrequiredCurrency id, or several separated by commas (up to 50).
Response200
{
  "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.

GET/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.
ParameterTypeDescription
uidstringoptionalOnly this customer.
psys_cidlistoptionalOnly these currencies.
pageintegeroptionalPage number, from 1.Default: 1
limitintegeroptionalItems 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".

FieldTypeMeaning
txn_idstringId of the top-up.
deposit_uidstringThe customer uid.
amount, deposit_sum, invoice_sum, invoice_total_sumdecimalThe amount received.
currency, psys_cidstringCurrency code and id.
statusstringcompleted, or error for a reverted top-up.
confirmationsstringConfirmations of the transaction.
wallet_hash, tx_urls, qr_codestring / arrayThe deposit address, the explorer link, a QR code of the address.
source_currency, source_rate, source_amountstringUSD value at the time of confirmation, when a rate was available.
merchant, merchant_id, pending_amount, invoice_commission, commentstringAs in invoice callbacks (pending_amount and the commission are zero).
verify_hashstringSigned 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.

GETPOST/api/v1/operations/withdrawCreates a withdrawal to one address (cash_out) or to several (mass_cash_out).
ParameterTypeDescription
currencystringrequiredCurrency id to send (psys_cid is accepted too).
tolistrequiredRecipient address, or several separated by commas (up to 100, each at most once, not the hot wallet itself).
amountlistrequiredAmount for each address in the same order, comma-separated; each at least the currency’s minimum.
typestringoptionalcash_out (exactly one address) or mass_cash_out (several).Default: cash_out
feePlanstringoptionalNetwork fee level: normal or priority (fee_plan is accepted too).Default: normal
idempotency_keystringoptionalUp 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
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 (see error);
  • 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.

GET/api/v1/operations/fee/:psys_cidEstimates the network fee of a withdrawal. data = { fee, currency, psys_cid, plan } — the total, in the native coin.
ParameterTypeDescription
addresseslistrequiredRecipient addresses, comma-separated.
amountslistrequiredOne amount per address.
feePlanstringoptionalnormal 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.

GET/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.

Errors

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.

CodeHTTPNameMeaning
101401UnauthorizedThe API key is missing or wrong, or the shop or its account is disabled.
102403ForbiddenThe request is not allowed: the IP address is not in the shop’s allowlist, the shop is disabled, or withdrawals are stopped.
103400Bad RequestA required parameter is missing; the message names it.
104422Unprocessable entityA parameter has an invalid value; the message names it and says why.
105422Unprocessable entityUnknown currency id.
106422Unprocessable entityAn invoice with this order_number already exists in this shop (send return_existing=true to get it back instead).
107422Unprocessable entityThe amount is below the currency’s minimum.
108500Internal Server ErrorAn unexpected error on the gateway’s side. Retry later.
109503Service UnavailableNo fresh exchange rate for this currency or fiat right now. Retry later or price the invoice in crypto.
110422Unprocessable entityThe shop has no receiving wallet for this currency (or the currency is not enabled for the shop).
111404Not FoundThe invoice, operation or route does not exist (or belongs to another shop).
112429Too Many RequestsA per-minute limit was reached. Wait and retry.
113409ConflictThe 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.
115400Bad RequestThe network fee cannot be estimated (often: the balance cannot cover it, or cannot be read right now).
116422Unprocessable entityThe hot wallet balance is not enough for the withdrawal and its network fee.
117403ForbiddenWithdrawals are not possible: they are disabled for API use, or there is no managed wallet on that network.
118429Too Many RequestsA standing quota is used up (open invoices, deposit addresses, currency switches of one order).
124402Payment RequiredThe 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.

IdCoinNameNetwork
BTCBTCBitcoinBitcoin
LTCLTCLitecoinLitecoin
DOGEDOGEDogecoinDogecoin
TZECZECZcashZcash
ETHETHEthereumEthereum
USDTUSDTTether ERC-20Ethereum
USDCUSDCUSD Coin ERC-20Ethereum
USDC_BASEUSDCUSD Coin (Base)Base
BNBBNBBNBBNB Smart Chain
USDT_BSCUSDTTether BEP-20BNB Smart Chain
USDC_BSCUSDCUSD Coin BEP-20BNB Smart Chain
TRXTRXTronTron
USDT_TRXUSDTTether TRC-20Tron
XMRXMRMoneroMonero
SOLSOLSolanaSolana
USDT_SOLUSDTTether (Solana)Solana
USDC_SOLUSDCUSD Coin (Solana)Solana
GRAMGRAMGram (TON)TON
USDT_TONUSDTTether (TON)TON