Разработчикам
Документация API TorPayment
Создавайте счета, получайте подписанные уведомления, выдавайте клиентам постоянные адреса пополнения и отправляйте выводы — обычными HTTPS-запросами из любого языка.
Обзор
API TorPayment позволяет сайту создавать счета, узнавать их состояние, выдавать клиентам постоянные адреса пополнения и — если вы это включите — отправлять выводы. Это обычный HTTPS: каждый метод отвечает в JSON, а любой параметр можно передать в строке запроса, так что достаточно простого GET-запроса. Методы с пометкой POST принимают параметры и в теле запроса — как форму (application/x-www-form-urlencoded) или JSON; если параметр есть и там и там, используется значение из тела.
- Создайте магазин в панели мерчанта и скопируйте его API-ключ.
- Подключите кошелёк для каждой сети, в которой хотите принимать оплату. Валюту без кошелька использовать нельзя (ошибка 110).
- Отправляйте запросы на базовый адрес ниже и обрабатывайте уведомления, которые получает ваш сервер.
Аутентификация
Каждый запрос передаёт 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).
{
"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
}
}Ограничения
- 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 КБ.
Создание счёта
/api/v1/invoices/newСоздаёт счёт с отдельным адресом для оплаты и возвращает ссылку на страницу оплаты.Укажите цену либо в фиате (source_amount + source_currency: сумма в криптовалюте считается по текущему курсу), либо сразу в криптовалюте (amount в currency). Отправьте покупателя на invoice_url: страница оплаты показывает адрес, точную сумму, QR-код, таймер и статус в реальном времени. При смене статуса ваш сервер получает уведомление.
Параметры
| Параметр | Тип | Описание | |
|---|---|---|---|
order_number | string | обязательный | Номер вашего заказа, до 255 символов. Уникален в пределах магазина: второй счёт с тем же номером отклоняется (код 106). |
order_name | string | обязательный | За что платят, до 255 символов; видно покупателю. |
source_amount | decimal | необязательный | Цена в фиате, например 49.90. Требует source_currency. |
source_currency | string | необязательный | Код фиата для source_amount, например USD, EUR. Требует source_amount. |
amount | decimal | необязательный | Цена в криптовалюте, в currency, не больше знаков, чем у этой валюты. Обязательна, если не передан source_amount; если переданы оба, используется цена в фиате. |
currency | string | необязательный | Идентификатор валюты для оплаты, например USDT_TRX. Если указан, страница оплаты сразу показывает реквизиты.По умолчанию: первая из allowed_psys_cids, иначе первая валюта, которую принимает магазин; покупатель выбирает её на странице оплаты. |
allowed_psys_cids | list | необязательный | Валюты через запятую, из которых может выбрать покупатель (до 50). Для каждой у магазина должен быть кошелёк.По умолчанию: все валюты, которые принимает магазин. |
description | string | необязательный | Подробное описание, до 2 000 символов. |
email | string | необязательный | E-mail покупателя, сохраняется в счёте (по нему можно искать в списке операций). |
expire_min | integer | необязательный | Сколько минут есть на оплату, 1–10 080.По умолчанию: настройка магазина (60, если вы её не меняли). |
callback_url | URL | необязательный | Куда отправлять уведомления о статусе этого счёта. Добавьте json=true в строку запроса адреса, чтобы получать JSON вместо данных формы.По умолчанию: адрес Status URL магазина. |
success_callback_url | URL | необязательный | Дополнительное уведомление при оплате (отправляется, только если адрес отличается от адреса статуса).По умолчанию: Success URL магазина. |
fail_callback_url | URL | необязательный | Дополнительное уведомление, если счёт истёк или завершился ошибкой (отправляется, только если адрес отличается от адреса статуса).По умолчанию: Fail URL магазина. |
success_invoice_url | URL | необязательный | Куда покупатель попадает после оплаты: страница оплаты отправляет его туда через 5 секунд после подтверждения платежа (он может остаться), туда же ведёт кнопка «Вернуться в магазин». |
fail_invoice_url | URL | необязательный | Ссылка «Вернуться в магазин», если счёт истёк, отменён или завершился ошибкой.По умолчанию: success_invoice_url. |
language | string | необязательный | Язык страницы оплаты: en или ru. Параметр ?lang= в ссылке на страницу важнее. |
return_existing | boolean | необязательный | true: если для номера заказа уже есть счёт, вернуть его вместо ошибки 106. Удобно для повторных запросов.По умолчанию: false |
redirect_to_invoice | boolean | необязательный | true: ответить редиректом 302 на страницу оплаты вместо JSON (для формы в браузере, которая отправляется сразу сюда).По умолчанию: false |
plugin | string | необязательный | Название вашей интеграции (до 60 символов); сохраняется в счёте. |
version | string | необязательный | Версия вашей интеграции (до 30 символов). |
- Адреса уведомлений — только
httpилиhttpsна публичном адресе, порт 80, 443 или от 1024 (порты баз данных и RPC узлов запрещены), без логина и пароля и не на самом шлюзе. - Счёт с ценой в фиате можно оплатить любой разрешённой валютой: когда покупатель меняет валюту, создаётся новый счёт того же заказа со своим адресом и суммой по текущему курсу от той же цены в фиате. Счёт с ценой в криптовалюте тоже получает стоимость в USD, если курс доступен, и тогда валюту можно сменить так же; без курса он привязан к своей валюте.
Пример
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"}'Ответ
{
"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_id | string | Идентификатор счёта. |
invoice_url | string | Страница оплаты, на которую нужно отправить покупателя. |
amount | decimal | Сумма к оплате в currency. |
pending_amount | decimal | Сколько ещё не хватает (для нового счёта — вся сумма). |
wallet_hash | string | Адрес для оплаты, уникальный для этого счёта. |
psys_cid | string | Идентификатор валюты счёта. |
currency | string | Код валюты (совпадает с идентификатором, кроме нескольких старых, например ZEC для TZEC). |
status | string | Статус счёта. |
source_currency | string | Фиат цены (для счёта в криптовалюте — USD, если был доступен курс), иначе пусто. |
source_rate | decimal | Сколько единиц currency приходится на 1 единицу source_currency, иначе пусто. |
expire_utc | integer | Когда истекает счёт (секунды Unix). |
expected_confirmations | string | Сколько подтверждений нужно платежу в этой сети. |
qr_code | string | QR-код платёжного запроса в виде URI data:image/png;base64. |
invoice_commission | decimal | Всегда ноль: шлюз не берёт комиссию. |
invoice_sum, invoice_total_sum | decimal | Сумма к оплате (то же, что amount). |
verify_hash | string | HMAC-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-ключ, и каждый видит только магазин, которому принадлежит ключ.
Получить счёт
/api/v1/invoices/:idОдин счёт подробно: data.invoice — объект операции (поля ниже).curl -H "X-Api-Key: YOUR_API_KEY" "https://torpayment.net/api/v1/invoices/6564f9b0c8e2a1d4f7b3e901"| Поле | Тип | Значение |
|---|---|---|
id | string | Идентификатор операции (для счёта — идентификатор счёта). |
type | string | invoice, cash_in (пополнение адреса депозита), cash_out или mass_cash_out (выводы). |
status | string | Статус операции; для счетов см. статусы. |
status_code | integer | 3, если операция завершена (иначе поля нет). |
psys_cid, currency | string | Идентификатор и код валюты. |
sum | decimal | Счёт: сумма к оплате. Пополнение и вывод: сумма. |
amount | decimal | Счёт: всё полученное, подтверждённое и нет. |
pending_sum | decimal | Счёт: получено, но ещё не подтверждено. Вывод: ещё не выполнено. |
actual_sum, actual_invoice_sum | decimal | Счёт: подтверждённая сумма. |
commission, actual_commission, actual_fee | decimal | Для счетов всегда ноль: комиссии нет. |
source_currency, source_rate | string | Как в ответе на создание счёта. |
wallet_hash | string | Адрес оплаты (вывод: получатель или горячий кошелёк для пакетного вывода). |
params | object | Счёт: order_number, order_name, description, source_amount, source_currency, source_rate, currency, amount. Пополнение: deposit_uid, currency, amount. |
tx_id, tx_url | array | Идентификаторы транзакций в блокчейне и ссылки на них в обозревателе. |
confirmations | integer | Подтверждения наименее подтверждённого платежа. |
created_at_utc, expire_at_utc | integer | Секунды Unix (expire_at_utc равно null для пополнений и выводов). |
parent_id | string | Есть, если счёт создан сменой валюты: идентификатор первого счёта заказа. |
child_ids | array | В подробном виде первого счёта заказа: идентификаторы счетов, созданных сменой валюты. |
finished_at_utc | integer | В подробном виде: когда счёт оплачен (или null). |
invoice_url | string | В подробном виде: страница оплаты. |
shop_id | string | Идентификатор магазина. |
user_id | integer | Всегда 1 (оставлено для совместимости). |
Список операций
/api/v1/operationsСчета, пополнения депозитов и выводы магазина, сначала новые.| Параметр | Тип | Описание | |
|---|---|---|---|
page | integer | необязательный | Номер страницы, с 1.По умолчанию: 1 |
limit | integer | необязательный | Элементов на странице, 1–100 (принимается и per-page).По умолчанию: 10 |
type | string | необязательный | invoice, cash_in, cash_out или mass_cash_out. |
status | string | необязательный | Только операции в этом статусе. |
currency | string | необязательный | Только эта валюта. |
search | string | необязательный | Точное совпадение (без учёта регистра) с идентификатором, номером заказа, e-mail покупателя или идентификатором транзакции; для пополнений — и с uid клиента, для выводов — с адресом получателя. |
data.operations — список (счета здесь без полей подробного вида). В data._meta — totalCount, pageCount, currentPage и perPage; в data._links — self, first, last и, если есть, next.
/api/v1/operations/:idОдна операция по идентификатору: счёт (подробно), пополнение депозита или вывод. data — сам объект операции.Валюты и курсы
/api/v1/currenciesВсе валюты шлюза с курсом в USD./api/v1/currencies/:fiatТо же с курсами в другом фиате, например /api/v1/currencies/EUR.| Поле | Тип | Значение |
|---|---|---|
cid | string | Идентификатор валюты. |
currency, name | string | Код и название. |
icon | string | Адрес значка монеты на этом шлюзе. |
precision | string | Число знаков после запятой. |
min_sum_in | decimal | Минимальная сумма счёта. |
hidden | integer | 0: магазин может принять её сейчас; 1: не может (нет кошелька или она не включена для магазина). |
maintenance | boolean | true, если нет свежего курса: тогда её нельзя использовать для счетов с ценой в фиате. |
price_usd | decimal | Цена одной монеты в USD. |
rate_usd, fiat_rate | decimal | Монет за 1 USD и за 1 единицу запрошенного фиата. |
fiat | string | Фиат для fiat_rate. |
invoice_commission_percentage | string | Всегда "0". |
Балансы
/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.
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_id | string | Идентификатор счёта. |
ipn_type | string | invoice (пополнения: pay_in; выводы: cash_out / mass_cash_out). |
merchant, merchant_id | string | Название и идентификатор магазина. |
order_number, order_name | string | Как переданы при создании счёта. |
status | string | Статус счёта. |
amount | decimal | Пока счёт открыт: всё полученное, подтверждённое и нет. После оплаты (completed, mismatch): только подтверждённые деньги, по этой сумме можно зачислять. Перевод, пришедший позже, вызовет уведомление ещё раз с большей суммой: обрабатывайте каждый идентификатор события один раз. |
seen_amount | decimal | Всё полученное, подтверждённое и нет, в любом статусе. |
confirmed_amount | decimal | Только подтверждённые деньги, в любом статусе. |
pending_amount | decimal | Сколько не хватает до полной цены (не меньше нуля). |
invoice_sum, invoice_total_sum | decimal | Сумма к оплате. |
invoice_commission | decimal | Всегда ноль. |
currency, psys_cid | string | Код и идентификатор валюты. |
source_currency, source_amount, source_rate | string | Цена в фиате, если есть (иначе пустые строки). |
confirmations | string | Подтверждения наименее подтверждённого платежа. |
wallet_hash | string | Адрес счёта. |
tx_urls | array | Ссылки на платежи в обозревателе (в режиме формы — строка JSON). |
qr_code | string | QR-код в виде data URI. |
expire_utc | integer | Срок, секунды Unix. |
comment | string | Строка со ссылкой на страницу оплаты. |
switch_id | string | Только для счёта, созданного сменой валюты: идентификатор первого счёта заказа. |
verify_hash | string | Подпись, см. ниже. |
Проверка уведомления
Каждое уведомление подписано дважды вашим API-ключом. Достаточно проверить любую из подписей; verify_hash подходит для существующих интеграций, заголовок добавляет метку времени.
verify_hash, режим JSON: HMAC-SHA1 (hex) отJSON.stringifyполученного объекта безverify_hash, ключи в порядке получения, без пробелов.verify_hash, режим формы: HMAC-SHA1 (hex) от PHPserialize()всех полей, кромеverify_hash, отсортированных по имени (ksort). Все значения — строки; длины считаются в байтах UTF-8.- Заголовок
X-TorPayment-Signature: t=<секунды unix>,v1=<hex>:v1— HMAC-SHA256 от<t>.<canonical>, где canonical — тело запроса как есть в режиме JSON и та же строкаserialize(), что выше, в режиме формы. Отклоняйте уведомления, у которыхtотличается от ваших часов больше чем на 5 минут.
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)В режиме формы значение 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 — на общий). О каждом пополнении приходит уведомление, когда оно подтверждено.
/api/v1/shops/deposit/newВозвращает адрес клиента; при первом вызове создаёт его.| Параметр | Тип | Описание | |
|---|---|---|---|
uid | string | обязательный | Ваш идентификатор клиента, до 255 символов. |
psys_cid | list | обязательный | Идентификатор валюты или несколько через запятую (до 50). |
{
"status": "success",
"data": { "uid": "customer-42", "hash": "TJx2Lq5w8Hc3VbN6kq7r8LqP4sZt1yUe9D", "psys_cid": "USDT_TRX" }
}data — один объект для одной валюты или массив таких объектов, если в psys_cid их несколько. hash — адрес. Ошибки: 105 — неизвестная валюта, 110 — валюта не включена для магазина или для неё нет кошелька, 112 / 118 — ограничения.
/api/v1/shops/depositАдреса пополнения магазина, сначала новые: массив { uid, hash, psys_cid }, по записи на каждую валюту сети адреса.| Параметр | Тип | Описание | |
|---|---|---|---|
uid | string | необязательный | Только этот клиент. |
psys_cid | list | необязательный | Только эти валюты. |
page | integer | необязательный | Номер страницы, с 1.По умолчанию: 1 |
limit | integer | необязательный | Элементов на странице, 1–100.По умолчанию: 20 |
Пополнения — операции типа cash_in (Список операций). Уведомление о пополнении приходит на Status URL магазина (и на Success URL, если он другой) с ipn_type: "pay_in" и status: "completed", когда пополнение подтверждено. Если пополнение, о котором вы уже узнали, позже откатилось в блокчейне, второе уведомление придёт со status: "error".
| Поле | Тип | Значение |
|---|---|---|
txn_id | string | Идентификатор пополнения. |
deposit_uid | string | uid клиента. |
amount, deposit_sum, invoice_sum, invoice_total_sum | decimal | Полученная сумма. |
currency, psys_cid | string | Код и идентификатор валюты. |
status | string | completed или error для откатившегося пополнения. |
confirmations | string | Подтверждения транзакции. |
wallet_hash, tx_urls, qr_code | string / array | Адрес депозита, ссылка в обозревателе, QR-код адреса. |
source_currency, source_rate, source_amount | string | Стоимость в USD на момент подтверждения, если был доступен курс. |
merchant, merchant_id, pending_amount, invoice_commission, comment | string | Как в уведомлениях по счетам (pending_amount и комиссия равны нулю). |
verify_hash | string | Подписано так же, как уведомления по счетам. |
Выводы
Выводы уходят с управляемого горячего кошелька магазина, поэтому они возможны только в сетях, где у магазина есть управляемый кошелёк, и только если на шлюзе работает подписант. Для API они выключены, пока вы не включите их для магазина в панели. При ручном подтверждении (по умолчанию) созданный здесь вывод ждёт в статусе new, пока его не подтвердят в панели.
/api/v1/operations/withdrawСоздаёт вывод на один адрес (cash_out) или на несколько (mass_cash_out).| Параметр | Тип | Описание | |
|---|---|---|---|
currency | string | обязательный | Идентификатор валюты для отправки (принимается и psys_cid). |
to | list | обязательный | Адрес получателя или несколько через запятую (до 100, каждый не больше одного раза, не сам горячий кошелёк). |
amount | list | обязательный | Сумма для каждого адреса в том же порядке, через запятую; каждая не меньше минимума валюты. |
type | string | необязательный | cash_out (ровно один адрес) или mass_cash_out (несколько).По умолчанию: cash_out |
feePlan | string | необязательный | Уровень комиссии сети: normal или priority (принимается и fee_plan).По умолчанию: normal |
idempotency_key | string | необязательный | До 100 символов, либо заголовок Idempotency-Key. Повтор запроса с тем же ключом возвращает уже созданный вывод; тот же ключ с другими адресами или суммами отклоняется (409, код 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"Суммы и оценка комиссий сети резервируются на балансе горячего кошелька при создании вывода, поэтому два вывода никогда не обещают одни и те же монеты; комиссия платится в родной монете сети. 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, подписанное так же, как остальные.
/api/v1/operations/fee/:psys_cidОценка комиссии сети за вывод. data = { fee, currency, psys_cid, plan } — итог в родной монете сети.| Параметр | Тип | Описание | |
|---|---|---|---|
addresses | list | обязательный | Адреса получателей через запятую. |
amounts | list | обязательный | По сумме на каждый адрес. |
feePlan | string | необязательный | normal или priority.По умолчанию: normal |
Не больше 20 запросов в минуту на API-ключ. Для первых 20 получателей комиссию считает сеть; для каждого следующего берётся самая высокая из них.
/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 — конфликт ключа идемпотентности.
Платёжные ссылки
Платёжная ссылка — это товар с ценой, который вы создаёте в панели. Её публичный адрес https://torpayment.net/pay/<slug> показывает товар и спрашивает у покупателя e-mail; каждый раз, когда он указан, создаётся новый счёт, и покупатель переходит на страницу оплаты выбирать валюту. Одну ссылку можно разместить где угодно, и её может оплатить сколько угодно покупателей — каждый по своему счёту и на свой адрес. Просмотр ссылки ничего не создаёт. Вызывать API не нужно.
Необязательные параметры запроса:
ref— ваша метка покупателя (буквы, цифры и_ . : @ -, до 64 символов). Она возвращается вorder_numberуведомления как<slug>-<ref>-<случайная часть>; без неё номер заказа —<slug>-<случайная часть>.email— e-mail покупателя, если он вам уже известен: вопрос пропускается, счёт создаётся сразу, адрес сохраняется в нём.lang— язык страницы оплаты,enилиru.
Неподходящее значение не вызывает ошибку, а просто игнорируется, поэтому ссылка всегда открывается. E-mail покупателя хранится в счёте: панель показывает его на странице счёта. Уведомления приходят на адреса магазина, как для любого счёта.
https://torpayment.net/pay/premium-plan?ref=user-1842&lang=enОшибки
Каждая ошибка возвращает свой HTTP-статус и {"status":"error","data":{"name","message","code"}}. В программе используйте code, а message показывайте или пишите в журнал. Тело, которое не удаётся разобрать или которое слишком велико, даёт 400 или 413 с кодом 104; неизвестный путь /api/ — 404 с кодом 111.
| Код | HTTP | Название | Значение |
|---|---|---|---|
| 101 | 401 | Unauthorized | API-ключ не передан или неверен, либо магазин или его аккаунт отключён. |
| 102 | 403 | Forbidden | Запрос не разрешён: IP-адреса нет в списке разрешённых для магазина, магазин отключён или выводы остановлены. |
| 103 | 400 | Bad Request | Не передан обязательный параметр; он назван в сообщении. |
| 104 | 422 | Unprocessable entity | У параметра недопустимое значение; в сообщении указан параметр и причина. |
| 105 | 422 | Unprocessable entity | Неизвестный идентификатор валюты. |
| 106 | 422 | Unprocessable entity | Счёт с таким order_number в этом магазине уже есть (передайте return_existing=true, чтобы получить его вместо ошибки). |
| 107 | 422 | Unprocessable entity | Сумма меньше минимальной для валюты. |
| 108 | 500 | Internal Server Error | Непредвиденная ошибка на стороне шлюза. Повторите позже. |
| 109 | 503 | Service Unavailable | Сейчас нет свежего курса для этой валюты или фиата. Повторите позже или укажите сумму в криптовалюте. |
| 110 | 422 | Unprocessable entity | У магазина нет кошелька для приёма этой валюты (или валюта не включена для магазина). |
| 111 | 404 | Not Found | Счёт, операция или адрес не существует (или принадлежит другому магазину). |
| 112 | 429 | Too Many Requests | Достигнут поминутный лимит. Подождите и повторите. |
| 113 | 409 | Conflict | Запрос противоречит текущему состоянию, например ключ идемпотентности уже использован для другого вывода или в пуле заранее подготовленных адресов кошелька не осталось свободных. |
| 115 | 400 | Bad Request | Не удаётся оценить комиссию сети (чаще всего баланса на неё не хватает или его сейчас не прочитать). |
| 116 | 422 | Unprocessable entity | Баланса горячего кошелька не хватает на вывод и комиссию сети. |
| 117 | 403 | Forbidden | Вывод невозможен: он выключен для API или в этой сети нет управляемого кошелька. |
| 118 | 429 | Too Many Requests | Исчерпана квота (открытые счета, адреса пополнения, смены валюты одного заказа). |
| 124 | 402 | Payment Required | Разовая плата за доступ для аккаунта ещё не внесена. |
Идентификаторы валют
Используйте эти идентификаторы в currency, allowed_psys_cids и psys_cid (регистр не важен). Токен без суффикса — это токен сети Ethereum: USDT — Tether ERC-20, а Tether в сети Tron — USDT_TRX. Вместо GRAM принимается TON. Магазин может принять валюту, только если у него есть кошелёк в её сети — см. hidden в разделе Валюты.
| Идентификатор | Монета | Название | Сеть |
|---|---|---|---|
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 |