Криптоплатёжный шлюз

Разработчикам

Документация API TorPayment

Создавайте счета, получайте подписанные уведомления, выдавайте клиентам постоянные адреса пополнения и отправляйте выводы — обычными HTTPS-запросами из любого языка.

Базовый адресhttps://torpayment.net/api/v1API-ключи в панели

Обзор

API TorPayment позволяет сайту создавать счета, узнавать их состояние, выдавать клиентам постоянные адреса пополнения и — если вы это включите — отправлять выводы. Это обычный HTTPS: каждый метод отвечает в JSON, а любой параметр можно передать в строке запроса, так что достаточно простого GET-запроса. Методы с пометкой POST принимают параметры и в теле запроса — как форму (application/x-www-form-urlencoded) или JSON; если параметр есть и там и там, используется значение из тела.

  1. Создайте магазин в панели мерчанта и скопируйте его API-ключ.
  2. Подключите кошелёк для каждой сети, в которой хотите принимать оплату. Валюту без кошелька использовать нельзя (ошибка 110).
  3. Отправляйте запросы на базовый адрес ниже и обрабатывайте уведомления, которые получает ваш сервер.
Базовый адресhttps://torpayment.net/api/v1

Аутентификация

Каждый запрос передаёт API-ключ магазина одним из трёх способов (проверяются в этом порядке):

  • параметр api_key в строке запроса или в теле;
  • заголовок X-Api-Key: <ключ>;
  • заголовок Authorization: Bearer <ключ>.

Отсутствующий или неверный ключ, отключённый магазин и отключённый аккаунт дают ответ 401 (код 101). Если у магазина задан список разрешённых IP (настройка магазина в панели), запросы с других адресов получают 403 (код 102). Пока разовая плата за доступ к аккаунту не внесена, любой запрос получает 402 (код 124).

API-ключ — это ещё и секрет, которым подписываются уведомления (verify_hash, X-TorPayment-Signature). Храните его только на сервере. Шлюз не пишет ключи из адресов в свои журналы, но промежуточные прокси могут: лучше передавать ключ в заголовке, а не в api_key в строке запроса.

Ответы

Успешный вызов отвечает HTTP 200 с status: "success" и результатом в data. Ошибка возвращает HTTP-статус ошибки с status: "error" и полями data.name, data.message и data.code.

  • Суммы — десятичные строки со всеми знаками валюты, например "49.900000" для USDT в сети Tron.
  • Время (expire_utc, created_at_utc …) — секунды Unix, UTC.
  • Идентификаторы счетов, пополнений и выводов — 24 шестнадцатеричных символа в нижнем регистре.
  • Ответы не кэшируются (Cache-Control: no-store).
Успех200
{
  "status": "success",
  "data": { "txn_id": "6564f9b0c8e2a1d4f7b3e901", "invoice_url": "https://torpayment.net/invoice/6564f9b0c8e2a1d4f7b3e901" }
}
Ошибка422
{
  "status": "error",
  "data": {
    "name": "Unprocessable entity",
    "message": "Invalid attribute value: {\"amount\":\"must be greater than zero\"}",
    "code": 104
  }
}

Ограничения

  • 600 запросов в минуту на клиента (адрес IPv4 или сеть IPv6 /64) на весь сервер. Сверх этого — 429, код 112.
  • 300 запросов в минуту на один API-ключ в этом API, с каких бы адресов они ни шли, — отдельный лимит вашего магазина, который не расходует никто другой. Сверх этого — 429, код 112.
  • 120 новых счетов в минуту на магазин (смена валюты заказа покупателем не считается): 429, код 112.
  • 10 000 заказов, ожидающих оплаты (статус new или pending), на магазин: 429, код 118. С меньшим expire_min они освобождаются быстрее.
  • 30 смен валюты на один заказ на странице оплаты (код 118).
  • 120 новых адресов пополнения в минуту на магазин (код 112) и 10 000 всего на магазин (код 118).
  • 20 оценок комиссии в минуту на API-ключ; 100 получателей в одном выводе.
  • Тело запроса — до 256 КБ.

Создание счёта

GETPOST/api/v1/invoices/newСоздаёт счёт с отдельным адресом для оплаты и возвращает ссылку на страницу оплаты.

Укажите цену либо в фиате (source_amount + source_currency: сумма в криптовалюте считается по текущему курсу), либо сразу в криптовалюте (amount в currency). Отправьте покупателя на invoice_url: страница оплаты показывает адрес, точную сумму, QR-код, таймер и статус в реальном времени. При смене статуса ваш сервер получает уведомление.

Параметры

ПараметрТипОписание
order_numberstringобязательныйНомер вашего заказа, до 255 символов. Уникален в пределах магазина: второй счёт с тем же номером отклоняется (код 106).
order_namestringобязательныйЗа что платят, до 255 символов; видно покупателю.
source_amountdecimalнеобязательныйЦена в фиате, например 49.90. Требует source_currency.
source_currencystringнеобязательныйКод фиата для source_amount, например USD, EUR. Требует source_amount.
amountdecimalнеобязательныйЦена в криптовалюте, в currency, не больше знаков, чем у этой валюты. Обязательна, если не передан source_amount; если переданы оба, используется цена в фиате.
currencystringнеобязательныйИдентификатор валюты для оплаты, например USDT_TRX. Если указан, страница оплаты сразу показывает реквизиты.По умолчанию: первая из allowed_psys_cids, иначе первая валюта, которую принимает магазин; покупатель выбирает её на странице оплаты.
allowed_psys_cidslistнеобязательныйВалюты через запятую, из которых может выбрать покупатель (до 50). Для каждой у магазина должен быть кошелёк.По умолчанию: все валюты, которые принимает магазин.
descriptionstringнеобязательныйПодробное описание, до 2 000 символов.
emailstringнеобязательныйE-mail покупателя, сохраняется в счёте (по нему можно искать в списке операций).
expire_minintegerнеобязательныйСколько минут есть на оплату, 1–10 080.По умолчанию: настройка магазина (60, если вы её не меняли).
callback_urlURLнеобязательныйКуда отправлять уведомления о статусе этого счёта. Добавьте json=true в строку запроса адреса, чтобы получать JSON вместо данных формы.По умолчанию: адрес Status URL магазина.
success_callback_urlURLнеобязательныйДополнительное уведомление при оплате (отправляется, только если адрес отличается от адреса статуса).По умолчанию: Success URL магазина.
fail_callback_urlURLнеобязательныйДополнительное уведомление, если счёт истёк или завершился ошибкой (отправляется, только если адрес отличается от адреса статуса).По умолчанию: Fail URL магазина.
success_invoice_urlURLнеобязательныйКуда покупатель попадает после оплаты: страница оплаты отправляет его туда через 5 секунд после подтверждения платежа (он может остаться), туда же ведёт кнопка «Вернуться в магазин».
fail_invoice_urlURLнеобязательныйСсылка «Вернуться в магазин», если счёт истёк, отменён или завершился ошибкой.По умолчанию: success_invoice_url.
languagestringнеобязательныйЯзык страницы оплаты: en или ru. Параметр ?lang= в ссылке на страницу важнее.
return_existingbooleanнеобязательныйtrue: если для номера заказа уже есть счёт, вернуть его вместо ошибки 106. Удобно для повторных запросов.По умолчанию: false
redirect_to_invoicebooleanнеобязательныйtrue: ответить редиректом 302 на страницу оплаты вместо JSON (для формы в браузере, которая отправляется сразу сюда).По умолчанию: false
pluginstringнеобязательныйНазвание вашей интеграции (до 60 символов); сохраняется в счёте.
versionstringнеобязательныйВерсия вашей интеграции (до 30 символов).
  • Адреса уведомлений — только http или https на публичном адресе, порт 80, 443 или от 1024 (порты баз данных и RPC узлов запрещены), без логина и пароля и не на самом шлюзе.
  • Счёт с ценой в фиате можно оплатить любой разрешённой валютой: когда покупатель меняет валюту, создаётся новый счёт того же заказа со своим адресом и суммой по текущему курсу от той же цены в фиате. Счёт с ценой в криптовалюте тоже получает стоимость в USD, если курс доступен, и тогда валюту можно сменить так же; без курса он привязан к своей валюте.

Пример

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
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"}'

Ответ

Ответ200
{
  "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"
  }
}
ПолеТипЗначение
txn_idstringИдентификатор счёта.
invoice_urlstringСтраница оплаты, на которую нужно отправить покупателя.
amountdecimalСумма к оплате в currency.
pending_amountdecimalСколько ещё не хватает (для нового счёта — вся сумма).
wallet_hashstringАдрес для оплаты, уникальный для этого счёта.
psys_cidstringИдентификатор валюты счёта.
currencystringКод валюты (совпадает с идентификатором, кроме нескольких старых, например ZEC для TZEC).
statusstringСтатус счёта.
source_currencystringФиат цены (для счёта в криптовалюте — USD, если был доступен курс), иначе пусто.
source_ratedecimalСколько единиц currency приходится на 1 единицу source_currency, иначе пусто.
expire_utcintegerКогда истекает счёт (секунды Unix).
expected_confirmationsstringСколько подтверждений нужно платежу в этой сети.
qr_codestringQR-код платёжного запроса в виде URI data:image/png;base64.
invoice_commissiondecimalВсегда ноль: шлюз не берёт комиссию.
invoice_sum, invoice_total_sumdecimalСумма к оплате (то же, что amount).
verify_hashstringHMAC-SHA1 от JSON поля data без этого поля, с вашим API-ключом в качестве ключа.

Статусы счёта

Статус меняет только шлюз — по тому, что он видит в блокчейне. Конечные статусы (completed, mismatch, cancelled, cancelled duplicate, error) сами не меняются обратно; expired ещё может стать completed, если оператор примет опоздавший платёж. Выдавайте заказ только при completed или mismatch и сверяйте сумму и валюту в уведомлении.

СтатусКогдаЧто делать магазину
newСоздан; ничего ещё не пришло.Ждите.
pendingПлатёж замечен, но его ещё недостаточно: он не подтверждён или подтверждённой суммы меньше цены.Пока не выдавайте товар. Можно показать «платёж получен, ждём подтверждений».
completedОплачен: подтверждённые средства, пришедшие вовремя, покрывают цену (за вычетом допуска недоплаты, заданного для магазина).Выдайте заказ.
mismatchОплачен суммой больше цены, если в настройках магазина переплата отмечается так (по умолчанию переплаченный счёт — completed).Выдайте заказ; решите, что делать с излишком.
expiredВремя вышло (срок плюс льготный период магазина), а денег не хватило. Возможно, оплачен частично: смотрите amount. Счёт, по которому уже идёт достаточная сумма, не истекает, пока она подтверждается.Не выдавайте заказ. Если деньги пришли, урегулируйте с покупателем. О полной оплате после истечения срока узнаёт оператор и может её принять: тогда счёт становится completed, и вы получаете уведомление.
cancelledИстёк, и ничего не поступило; через 10 часов после создания.Ничего делать не нужно: заказ не оплачен.
cancelled duplicateПокупатель сменил валюту и оплатил другой счёт того же заказа; этот закрыт.Игнорируйте: оплаченный счёт заказа придёт со своим уведомлением.
errorБыл оплачен, но подтверждённые средства позже откатились в блокчейне (глубокая реорганизация).Считайте платёж не полученным; если заказ выдан, свяжитесь с покупателем.

Счета, операции, балансы

Методы только для чтения. Каждому нужен API-ключ, и каждый видит только магазин, которому принадлежит ключ.

Получить счёт

GET/api/v1/invoices/:idОдин счёт подробно: data.invoice — объект операции (поля ниже).
curl
curl -H "X-Api-Key: YOUR_API_KEY" "https://torpayment.net/api/v1/invoices/6564f9b0c8e2a1d4f7b3e901"
ПолеТипЗначение
idstringИдентификатор операции (для счёта — идентификатор счёта).
typestringinvoice, cash_in (пополнение адреса депозита), cash_out или mass_cash_out (выводы).
statusstringСтатус операции; для счетов см. статусы.
status_codeinteger3, если операция завершена (иначе поля нет).
psys_cid, currencystringИдентификатор и код валюты.
sumdecimalСчёт: сумма к оплате. Пополнение и вывод: сумма.
amountdecimalСчёт: всё полученное, подтверждённое и нет.
pending_sumdecimalСчёт: получено, но ещё не подтверждено. Вывод: ещё не выполнено.
actual_sum, actual_invoice_sumdecimalСчёт: подтверждённая сумма.
commission, actual_commission, actual_feedecimalДля счетов всегда ноль: комиссии нет.
source_currency, source_ratestringКак в ответе на создание счёта.
wallet_hashstringАдрес оплаты (вывод: получатель или горячий кошелёк для пакетного вывода).
paramsobjectСчёт: order_number, order_name, description, source_amount, source_currency, source_rate, currency, amount. Пополнение: deposit_uid, currency, amount.
tx_id, tx_urlarrayИдентификаторы транзакций в блокчейне и ссылки на них в обозревателе.
confirmationsintegerПодтверждения наименее подтверждённого платежа.
created_at_utc, expire_at_utcintegerСекунды Unix (expire_at_utc равно null для пополнений и выводов).
parent_idstringЕсть, если счёт создан сменой валюты: идентификатор первого счёта заказа.
child_idsarrayВ подробном виде первого счёта заказа: идентификаторы счетов, созданных сменой валюты.
finished_at_utcintegerВ подробном виде: когда счёт оплачен (или null).
invoice_urlstringВ подробном виде: страница оплаты.
shop_idstringИдентификатор магазина.
user_idintegerВсегда 1 (оставлено для совместимости).

Список операций

GET/api/v1/operationsСчета, пополнения депозитов и выводы магазина, сначала новые.
ПараметрТипОписание
pageintegerнеобязательныйНомер страницы, с 1.По умолчанию: 1
limitintegerнеобязательныйЭлементов на странице, 1–100 (принимается и per-page).По умолчанию: 10
typestringнеобязательныйinvoice, cash_in, cash_out или mass_cash_out.
statusstringнеобязательныйТолько операции в этом статусе.
currencystringнеобязательныйТолько эта валюта.
searchstringнеобязательныйТочное совпадение (без учёта регистра) с идентификатором, номером заказа, e-mail покупателя или идентификатором транзакции; для пополнений — и с uid клиента, для выводов — с адресом получателя.

data.operations — список (счета здесь без полей подробного вида). В data._meta — totalCount, pageCount, currentPage и perPage; в data._links — self, first, last и, если есть, next.

GET/api/v1/operations/:idОдна операция по идентификатору: счёт (подробно), пополнение депозита или вывод. data — сам объект операции.

Валюты и курсы

GET/api/v1/currenciesВсе валюты шлюза с курсом в USD.
GET/api/v1/currencies/:fiatТо же с курсами в другом фиате, например /api/v1/currencies/EUR.
ПолеТипЗначение
cidstringИдентификатор валюты.
currency, namestringКод и название.
iconstringАдрес значка монеты на этом шлюзе.
precisionstringЧисло знаков после запятой.
min_sum_indecimalМинимальная сумма счёта.
hiddeninteger0: магазин может принять её сейчас; 1: не может (нет кошелька или она не включена для магазина).
maintenancebooleantrue, если нет свежего курса: тогда её нельзя использовать для счетов с ценой в фиате.
price_usddecimalЦена одной монеты в USD.
rate_usd, fiat_ratedecimalМонет за 1 USD и за 1 единицу запрошенного фиата.
fiatstringФиат для fiat_rate.
invoice_commission_percentagestringВсегда "0".

Балансы

GET/api/v1/balances/:psys_ciddata = { psys_cid, currency, balance } для одной валюты.
  • С управляемым кошельком в этой сети: баланс горячего кошелька магазина по последнему чтению из блокчейна.
  • С собственным кошельком: подтверждённые платежи, которые шлюз видел и сам никуда не перемещал. Реальный баланс — в вашем кошельке.

Уведомления (callbacks)

Шлюз сообщает вашему серверу об изменениях HTTP-запросом POST — уведомлением (callback). Считайте его сигналом: проверьте подпись и действуйте по полю status. Текущее состояние всегда можно получить методом Получить счёт.

Когда они отправляются

  • Уведомление о статусе — на callback_url счёта, иначе на Status URL магазина — при каждой смене статуса или полученных сумм (новое подтверждение само по себе уведомления не вызывает).
  • Уведомление об успехе — на success_callback_url, иначе на Success URL магазина — когда счёт становится completed или mismatch, если этот адрес отличается от адреса статуса.
  • Уведомление о неудаче — на fail_callback_url, иначе на Fail URL магазина — когда счёт становится expired или error, если этот адрес отличается от адреса статуса.
  • Пополнения депозитов и выводы отправляют уведомления на Status URL магазина (пополнения — также на Success URL); см. депозиты и выводы.

Форма или JSON. По умолчанию тело — multipart/form-data (массивы, например tx_urls, передаются в нём строками JSON). Если в строке запроса адреса уведомлений есть json=true (например https://shop.example/callback?json=true), тело — application/json.

Уведомление по счёту (режим 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"
}

Поля уведомления по счёту

ПолеТипЗначение
txn_idstringИдентификатор счёта.
ipn_typestringinvoice (пополнения: pay_in; выводы: cash_out / mass_cash_out).
merchant, merchant_idstringНазвание и идентификатор магазина.
order_number, order_namestringКак переданы при создании счёта.
statusstringСтатус счёта.
amountdecimalПока счёт открыт: всё полученное, подтверждённое и нет. После оплаты (completed, mismatch): только подтверждённые деньги, по этой сумме можно зачислять. Перевод, пришедший позже, вызовет уведомление ещё раз с большей суммой: обрабатывайте каждый идентификатор события один раз.
seen_amountdecimalВсё полученное, подтверждённое и нет, в любом статусе.
confirmed_amountdecimalТолько подтверждённые деньги, в любом статусе.
pending_amountdecimalСколько не хватает до полной цены (не меньше нуля).
invoice_sum, invoice_total_sumdecimalСумма к оплате.
invoice_commissiondecimalВсегда ноль.
currency, psys_cidstringКод и идентификатор валюты.
source_currency, source_amount, source_ratestringЦена в фиате, если есть (иначе пустые строки).
confirmationsstringПодтверждения наименее подтверждённого платежа.
wallet_hashstringАдрес счёта.
tx_urlsarrayСсылки на платежи в обозревателе (в режиме формы — строка JSON).
qr_codestringQR-код в виде data URI.
expire_utcintegerСрок, секунды Unix.
commentstringСтрока со ссылкой на страницу оплаты.
switch_idstringТолько для счёта, созданного сменой валюты: идентификатор первого счёта заказа.
verify_hashstringПодпись, см. ниже.

Проверка уведомления

Каждое уведомление подписано дважды вашим API-ключом. Достаточно проверить любую из подписей; verify_hash подходит для существующих интеграций, заголовок добавляет метку времени.

  • verify_hash, режим JSON: HMAC-SHA1 (hex) от JSON.stringify полученного объекта без verify_hash, ключи в порядке получения, без пробелов.
  • verify_hash, режим формы: HMAC-SHA1 (hex) от PHP serialize() всех полей, кроме verify_hash, отсортированных по имени (ksort). Все значения — строки; длины считаются в байтах UTF-8.
  • Заголовок X-TorPayment-Signature: t=<секунды unix>,v1=<hex>: v1 — HMAC-SHA256 от <t>.<canonical>, где canonical — тело запроса как есть в режиме JSON и та же строка serialize(), что выше, в режиме формы. Отклоняйте уведомления, у которых t отличается от ваших часов больше чем на 5 минут.
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)

В режиме формы значение tx_urls никогда не содержит HTML-сущностей (&, который мог бы её начать, передаётся как JSON-экранирование \u0026), поэтому html_entity_decode в PHP ничего не меняет, а в других языках этот шаг не нужен.

Ответ, повторы и идемпотентность

  • Отвечайте любым статусом 2xx в течение 10 секунд. Всё остальное — другой статус, редирект (переходы по редиректам не выполняются), таймаут, отказ в соединении — неудачная попытка. Хост, который несколько раз подряд не ответил вовремя, получает более короткий таймаут и меньше параллельных отправок, пока снова не начнёт отвечать, поэтому отвечайте быстро, а долгую работу выполняйте потом. Начало вашего ответа видно в панели на странице «Уведомления».
  • Неудачное уведомление повторяется через 15 с, 1 мин, 5 мин, 15 мин, 1 ч, 3 ч, 6 ч, 12 ч, 24 ч, 24 ч, 24 ч: 12 попыток примерно за 94 часов, после чего оно помечается как недоставленное. Его можно отправить снова вручную на странице «Уведомления» в панели.
  • X-TorPayment-Event-Id обозначает одно уведомление и не меняется при повторах и ручной отправке: сохраняйте его и обрабатывайте каждый идентификатор один раз. Тело (и verify_hash) повтора совпадает с первой попыткой; новым будет только t в заголовке подписи.
  • Уведомления одного счёта на один адрес приходят по порядку: следующее ждёт, пока предыдущее не будет доставлено или не будет прекращено. Всё равно меняйте состояние заказа только вперёд (оплаченный заказ остаётся оплаченным).
  • Если у магазина уже 5 000 недоставленных уведомлений, новые уведомления лишь о том, что неоплаченный счёт истёк или отменён, в очередь не ставятся (в панели они видны как недоставленные). Уведомления о деньгах ставятся в очередь всегда.

Постоянные адреса пополнения

Выдайте клиенту личный адрес, который не меняется, например для пополнения баланса. Один uid клиента получает один адрес в каждой сети; все валюты этой сети приходят на один адрес (USDT и USDC в Ethereum — на общий). О каждом пополнении приходит уведомление, когда оно подтверждено.

GETPOST/api/v1/shops/deposit/newВозвращает адрес клиента; при первом вызове создаёт его.
ПараметрТипОписание
uidstringобязательныйВаш идентификатор клиента, до 255 символов.
psys_cidlistобязательныйИдентификатор валюты или несколько через запятую (до 50).
Ответ200
{
  "status": "success",
  "data": { "uid": "customer-42", "hash": "TJx2Lq5w8Hc3VbN6kq7r8LqP4sZt1yUe9D", "psys_cid": "USDT_TRX" }
}

data — один объект для одной валюты или массив таких объектов, если в psys_cid их несколько. hash — адрес. Ошибки: 105 — неизвестная валюта, 110 — валюта не включена для магазина или для неё нет кошелька, 112 / 118 — ограничения.

GET/api/v1/shops/depositАдреса пополнения магазина, сначала новые: массив { uid, hash, psys_cid }, по записи на каждую валюту сети адреса.
ПараметрТипОписание
uidstringнеобязательныйТолько этот клиент.
psys_cidlistнеобязательныйТолько эти валюты.
pageintegerнеобязательныйНомер страницы, с 1.По умолчанию: 1
limitintegerнеобязательныйЭлементов на странице, 1–100.По умолчанию: 20

Пополнения — операции типа cash_in (Список операций). Уведомление о пополнении приходит на Status URL магазина (и на Success URL, если он другой) с ipn_type: "pay_in" и status: "completed", когда пополнение подтверждено. Если пополнение, о котором вы уже узнали, позже откатилось в блокчейне, второе уведомление придёт со status: "error".

ПолеТипЗначение
txn_idstringИдентификатор пополнения.
deposit_uidstringuid клиента.
amount, deposit_sum, invoice_sum, invoice_total_sumdecimalПолученная сумма.
currency, psys_cidstringКод и идентификатор валюты.
statusstringcompleted или error для откатившегося пополнения.
confirmationsstringПодтверждения транзакции.
wallet_hash, tx_urls, qr_codestring / arrayАдрес депозита, ссылка в обозревателе, QR-код адреса.
source_currency, source_rate, source_amountstringСтоимость в USD на момент подтверждения, если был доступен курс.
merchant, merchant_id, pending_amount, invoice_commission, commentstringКак в уведомлениях по счетам (pending_amount и комиссия равны нулю).
verify_hashstringПодписано так же, как уведомления по счетам.

Выводы

Выводы уходят с управляемого горячего кошелька магазина, поэтому они возможны только в сетях, где у магазина есть управляемый кошелёк, и только если на шлюзе работает подписант. Для API они выключены, пока вы не включите их для магазина в панели. При ручном подтверждении (по умолчанию) созданный здесь вывод ждёт в статусе new, пока его не подтвердят в панели.

GETPOST/api/v1/operations/withdrawСоздаёт вывод на один адрес (cash_out) или на несколько (mass_cash_out).
ПараметрТипОписание
currencystringобязательныйИдентификатор валюты для отправки (принимается и psys_cid).
tolistобязательныйАдрес получателя или несколько через запятую (до 100, каждый не больше одного раза, не сам горячий кошелёк).
amountlistобязательныйСумма для каждого адреса в том же порядке, через запятую; каждая не меньше минимума валюты.
typestringнеобязательныйcash_out (ровно один адрес) или mass_cash_out (несколько).По умолчанию: cash_out
feePlanstringнеобязательныйУровень комиссии сети: normal или priority (принимается и fee_plan).По умолчанию: normal
idempotency_keystringнеобязательныйДо 100 символов, либо заголовок Idempotency-Key. Повтор запроса с тем же ключом возвращает уже созданный вывод; тот же ключ с другими адресами или суммами отклоняется (409, код 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"

Суммы и оценка комиссий сети резервируются на балансе горячего кошелька при создании вывода, поэтому два вывода никогда не обещают одни и те же монеты; комиссия платится в родной монете сети. data — вывод в виде операции: id, type, status, psys_cid, currency, amount (итого), fee и fee_currency (сначала оценка, потом фактическая), sendmany ({ адрес: сумма }), params.fee.plan, tx_id, tx_url, created_at_utc, finished_at_utc и error, если есть.

  • new — ждёт подтверждения в панели; approved — подтверждён, ждёт начала;
  • processing — отправляется, получатель за получателем;
  • completed — все переводы подтверждены; error — хотя бы один перевод не удался (см. error);
  • cancelled — отменён в панели до отправки.

При каждой смене статуса на Status URL магазина отправляется уведомление с ipn_type cash_out или mass_cash_out, подписанное так же, как остальные.

GET/api/v1/operations/fee/:psys_cidОценка комиссии сети за вывод. data = { fee, currency, psys_cid, plan } — итог в родной монете сети.
ПараметрТипОписание
addresseslistобязательныйАдреса получателей через запятую.
amountslistобязательныйПо сумме на каждый адрес.
feePlanstringнеобязательныйnormal или priority.По умолчанию: normal

Не больше 20 запросов в минуту на API-ключ. Для первых 20 получателей комиссию считает сеть; для каждого следующего берётся самая высокая из них.

GET/api/v1/operations/fee-plan/:psys_cidТекущая комиссия одного минимального вывода для каждого уровня: data = { psys_cid, currency, normal: { value, currency }, priority: { value, currency } }.

Возможные ошибки: 103 / 104 — нет параметра или он неверен (неверный адрес, сумм больше, чем адресов, cash_out с несколькими адресами), 105 — неизвестная валюта, 107 — сумма меньше минимальной, 115 — комиссию не оценить, 116 — не хватает баланса, 117 — выводы выключены или нет управляемого кошелька, 102 — магазин отключён или выводы остановлены, 113 — конфликт ключа идемпотентности.

Ошибки

Каждая ошибка возвращает свой HTTP-статус и {"status":"error","data":{"name","message","code"}}. В программе используйте code, а message показывайте или пишите в журнал. Тело, которое не удаётся разобрать или которое слишком велико, даёт 400 или 413 с кодом 104; неизвестный путь /api/ — 404 с кодом 111.

КодHTTPНазваниеЗначение
101401UnauthorizedAPI-ключ не передан или неверен, либо магазин или его аккаунт отключён.
102403ForbiddenЗапрос не разрешён: IP-адреса нет в списке разрешённых для магазина, магазин отключён или выводы остановлены.
103400Bad RequestНе передан обязательный параметр; он назван в сообщении.
104422Unprocessable entityУ параметра недопустимое значение; в сообщении указан параметр и причина.
105422Unprocessable entityНеизвестный идентификатор валюты.
106422Unprocessable entityСчёт с таким order_number в этом магазине уже есть (передайте return_existing=true, чтобы получить его вместо ошибки).
107422Unprocessable entityСумма меньше минимальной для валюты.
108500Internal Server ErrorНепредвиденная ошибка на стороне шлюза. Повторите позже.
109503Service UnavailableСейчас нет свежего курса для этой валюты или фиата. Повторите позже или укажите сумму в криптовалюте.
110422Unprocessable entityУ магазина нет кошелька для приёма этой валюты (или валюта не включена для магазина).
111404Not FoundСчёт, операция или адрес не существует (или принадлежит другому магазину).
112429Too Many RequestsДостигнут поминутный лимит. Подождите и повторите.
113409ConflictЗапрос противоречит текущему состоянию, например ключ идемпотентности уже использован для другого вывода или в пуле заранее подготовленных адресов кошелька не осталось свободных.
115400Bad RequestНе удаётся оценить комиссию сети (чаще всего баланса на неё не хватает или его сейчас не прочитать).
116422Unprocessable entityБаланса горячего кошелька не хватает на вывод и комиссию сети.
117403ForbiddenВывод невозможен: он выключен для API или в этой сети нет управляемого кошелька.
118429Too Many RequestsИсчерпана квота (открытые счета, адреса пополнения, смены валюты одного заказа).
124402Payment RequiredРазовая плата за доступ для аккаунта ещё не внесена.

Идентификаторы валют

Используйте эти идентификаторы в currency, allowed_psys_cids и psys_cid (регистр не важен). Токен без суффикса — это токен сети Ethereum: USDT — Tether ERC-20, а Tether в сети Tron — USDT_TRX. Вместо GRAM принимается TON. Магазин может принять валюту, только если у него есть кошелёк в её сети — см. hidden в разделе Валюты.

ИдентификаторМонетаНазваниеСеть
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