KosPay — API v1 для мерчантов
Базовый адрес: https://kospay.io/v1. Все запросы и ответы — JSON (Content-Type: application/json).
Актив — USDT; сети — TRON (TRC-20), Polygon, BSC (BEP-20) и TON (network: TRON по
умолчанию | POLYGON | BSC | TON). Балансы по сетям раздельные: что пришло в Polygon, выплачивается в Polygon.
Авторизация
API-ключ мерчанта выпускается в кабинете (раздел «API-ключ», показывается один раз) и передаётся в каждом запросе:
Authorization: Bearer cp_live_…
Без ключа или с отозванным ключом — 401. Ключ даёт доступ только к данным своего мерчанта:
чужие пользователи, платежи и выплаты не видны и не адресуемы.
Белый список IP (рекомендуется). В кабинете («Безопасность → Белый список IP для API», с кодом 2FA)
можно указать адреса или подсети своих серверов, например 194.127.179.175 или 10.0.0.0/24. Тогда
верный ключ с любого другого IP получит 403 — украденный ключ без вашего сервера бесполезен.
Пустой список — ключ работает с любого IP.
Суммы
- В леджерных полях (
amount,fee,credited,balance) — десятичные строки в USDT:"12.5". - Там, где сумма уходит в сеть (
amountRawвыплаты), — целое в единицах 10⁻⁶ USDT строкой:"5000000"= 5 USDT. Во всех сетях одинаково, включая BSC, где ончейн у USDT 18 знаков — пересчёт в единицы сети шлюз делает сам.
Идентификатор пользователя
userId — id пользователя в вашей системе (1–64 символа A-Za-z0-9_.:@-). KosPay хранит его как
есть и возвращает в событиях, чтобы вы знали, кому зачислять.
Приём платежей
POST /v1/payments — платёж (адрес на срок)
Основной способ приёма. Выдаёт адрес из пула на 60 минут — покажите пользователю адрес и срок.
Пришедшее в этот срок (плюс внутренний резерв в несколько часов на задержку биржи) зачисляется
этому пользователю и приходит вебхуком deposit.credited. Повторный вызов для пользователя с
неистёкшим платежом возвращает тот же платёж (адрес не меняется).
POST /v1/payments
{"userId": "1386", "network": "TRON"} // network необязателен: TRON | POLYGON | BSC | TON
201
{
"id": "4f965d7f-…",
"userId": "1386",
"address": "TA9Nwm8rDGsyx92d4xj5MCdMw7cV62RWga",
"network": "TRON",
"currency": "USDT",
"expiresAt": "2026-09-18T18:10:53.467Z",
"createdAt": "2026-09-18T17:10:53.467Z"
}
503 — все адреса пула заняты (крайне редко; повторите через минуту). 400 — сеть выключена.
Пул адресов — на сеть: у пользователя может быть одновременно активный платёж в TRON и в Polygon.
Для Polygon и BSC адрес — 0x… (один и тот же EVM-адрес в обеих сетях); пользователю нужно отправить
USDT именно в той сети, которую вы указали (на биржах — «USDT, сеть Polygon» / «USDT, сеть BSC
(BEP-20)»). Перевод в другой включённой EVM-сети на тот же адрес шлюз тоже увидит и зачислит — но на
баланс той сети, откуда он пришёл; перевод в невключённой сети (Ethereum, Arbitrum) — не увидит.
Для TON адрес — UQ… (свой кошелёк на каждого пользователя); пользователю нужно отправить USDT (jetton) в
сети TON — из Telegram Wallet, Tonkeeper и т.п. Комментарий (memo) не нужен.
Скажите пользователю не сохранять адрес: после срока он может быть выдан другому. Платёж, пришедший позже срока, попадает на ваш баланс со статусом «без пользователя» (см. ниже).
GET /v1/payments/quote : сколько отправить для заданного зачисления
Авторизация: API-ключ активного мерчанта, те же ограничения IP. Пример:
GET /v1/payments/quote?network=TRON&creditedAmountRaw=25000000
Authorization: Bearer <merchant-api-key>
{"network":"TRON","currency":"USDT","amount":"26.5","amountRaw":"26500000","creditedAmountRaw":"25000000","platformFeeRaw":"0","merchantFeeRaw":"1500000"}
Это только пример при сохранённой надбавке 1,50 USDT, не тариф нового мерчанта.
Поля *Raw остаются целыми строками в 10^-6 USDT. Для всех мерчантов и разрешённых
сетей новые котировки USDT выбирают минимальный amountRaw, кратный 100 микро-USDT
(0.0001 USDT), при котором зачисление не меньше запрошенного. Сумма округляется
только вверх: 12.345678 → 12.3457 USDT. Дополнительное строковое поле amount
равно amountRaw / 1000000, без незначащих конечных нулей: 26.5, 10, 0.0001.
Это готовая сумма для отображения и копирования в кошелёк, максимум четыре знака
после точки. Правило применяется к суммам новых счетов, не к фактическим поступлениям,
выплатам или истории операций. Всегда выполняется
amountRaw = creditedAmountRaw + platformFeeRaw + merchantFeeRaw.
База берётся из feeBps текущего мерчанта, надбавка из его настроек DEPOSIT выбранной
сети. Базовая комиссия для ответа округляется вверх до микро-USDT, зачисление вниз;
расхождение с точным Decimal леджера остаётся в пределах округления до микро-USDT
в пользу плательщика. Фактические суммы из deposit.credited и авторизованного статуса платежа
остаются источником зачисления. В настройках приёма и проводках ничего не меняется. Комиссии и зачисление котировки
рассчитываются от того же округлённого gross; остаток округления не становится отдельной
комиссией KosPay. Сохранённые суммы и целевой net ранее выданных счетов не меняются;
платёж с исходной точной суммой принимается по исходному порогу. Для остатка оплаты
показывается округлённая вверх рекомендация, а credited/complete считаются точно.
Сумма зачисления: положительное целое до 18 цифр. Сеть по умолчанию TRON, остальные только если включены и разрешены мерчанту. При ошибке настроек расчёт закрывается, нулевая комиссия не подставляется. Котировка не создаёт адрес/заказ, не резервирует курс или комиссии и возвращается с Cache-Control: no-store. Перед новым заказом получать свежую котировку; изменения комиссий после неё отражаются в фактическом зачислении, которое нужно проверять на стороне мерчанта.
GET /v1/payments/{id} — статус платежа
Тот же объект + deposits: [{id, txid, logIndex, amount, credited, status, createdAt}] — всё, что
пришло на адрес в рамках этого платежа. Удобно для поллинга, если не хотите вебхуки.
POST /v1/deposit-addresses — личный адрес пользователя (альтернатива)
Постоянный адрес, закреплённый за пользователем навсегда; повтор возвращает тот же. Всё, что приходит на него в любое время, зачисляется этому пользователю. Подходит для постоянных клиентов («свой кошелёк»).
POST /v1/deposit-addresses
{"userId": "1386", "network": "TRON"} // network необязателен: TRON | POLYGON | BSC | TON
201
{"userId": "1386", "address": "T…", "network": "TRON", "currency": "USDT"}
Пополнения
GET /v1/deposits?userId=&unassigned=1&cursor=
GET /v1/deposits/TRON/{txid}
Объект пополнения:
{
"id": "…", "userId": "1386", "paymentId": "4f965d7f-…",
"address": "T…", "network": "TRON", "currency": "USDT",
"txid": "…", "logIndex": 0,
"amount": "10", "fee": "0.2", "platformFee": "0.15", "merchantFee": "0.05", "credited": "9.8",
"confirmations": 20, "status": "CREDITED", "createdAt": "…"
}
Статусы: DETECTED (увидели в сети) → CONFIRMED (подтверждений достаточно) → CREDITED
(зачислено на баланс, вебхук отправлен) → SWEPT (собрано в накопитель шлюза; на баланс не влияет).
REJECTED — транзакция выпала из цепи (реорг), не зачисляется.
userId: null — пополнение без пользователя: деньги пришли на адрес пула вне срока платежа. Они
уже на вашем балансе, но ваша система о них не знает. Список — GET /v1/deposits?unassigned=1.
Назначить пользователю (один раз, отменить нельзя — после этого уйдёт deposit.credited):
POST /v1/deposits/{id}/assign
{"userId": "1386"}
→ 200 {"id": "…", "userId": "1386"} 409 — уже назначен
Баланс
GET /v1/balance?network=TRON → {"currency": "USDT", "network": "TRON", "balance": "4.85"}
GET /v1/balances → [{"currency": "USDT", "network": "TRON", "balance": "4.85"},
{"currency": "USDT", "network": "POLYGON", "balance": "0"},
{"currency": "USDT", "network": "BSC", "balance": "0"},
{"currency": "USDT", "network": "TON", "balance": "0"}]
Баланс мерчанта = все зачисленные пополнения минус выплаты (включая зарезервированные под выплаты в обработке). Балансы по сетям раздельные — шлюз не переливает ликвидность между сетями.
Выплаты
POST /v1/payouts
POST /v1/payouts
{
"network": "TRON", // необязательно: TRON | POLYGON | BSC | TON — списание с баланса этой сети
"userId": "1386",
"to": "TK4V55UH9D7MpkUNvWLMuzHGbVA3Z1YUqu", // для POLYGON / BSC — 0x-адрес, для TON — EQ…/UQ…
"amountRaw": "5000000",
"idempotencyKey": "withdraw-123",
"ipnUrl": "https://…" // необязательно: URL вебхука только для этой выплаты
}
201— заявка создана, сумма (+ комиссия шлюза, если задана) сразу зарезервирована на балансе. Комиссия вывода — база шлюза своя в каждой сети, фиксом за выплату: TRON — 3 USDT, BSC / Polygon / TON — 1 USDT. Удерживается из запрошенной суммы: с баланса мерчанта списывается ровноamountRawзапроса, получатель получаетamountRaw − комиссия. В ответе, списке выплат и вебхуке:requestedAmountRaw— запрошено,feeRaw— комиссия,amountRaw— ушло получателю. Сумма меньше комиссии —400. Сверху база мерчант может добавить свою надбавку по каждой сети (кабинет → «Комиссии»: процент, фикс или фикс + процент):feeRaw= вся комиссия, из неёplatformFeeRaw— шлюзу,merchantFeeRaw— надбавка, доход мерчанта (с его баланса не списывается). Расчёт заранее:GET /v1/payouts/quote?amountRaw=150000000&network=BSC(networkне указан — TRON) →{network, requestedAmountRaw, feeRaw, platformFeeRaw, merchantFeeRaw, amountRaw (получит получатель), ok}— покажите пользователю «к получению» до заявки. Ответ — объект выплаты со статусомPENDING.400— отклонено проверкой (адрес не той сети, адрес-контракт, адрес шлюза, недопустимыйipnUrl).409— недостаточно средств илиidempotencyKeyуже использован для другой выплаты.- Нет ответа (таймаут) — исход неизвестен: не возвращайте средства пользователю и не
создавайте новую заявку с другим ключом; повторите тот же запрос с тем же
idempotencyKey— это безопасно.
idempotencyKey (1–64 символа A-Za-z0-9_.-) уникален в пределах пары (userId, idempotencyKey):
повтор с тем же ключом не создаст вторую выплату и вернёт ту же заявку.
Объект выплаты:
{
"id": "…", "userId": "1386", "idempotencyKey": "withdraw-123",
"to": "T…", "amountRaw": "5000000", "network": "TRON", "currency": "USDT",
"status": "PENDING", "txid": null, "reason": null,
"createdAt": "…", "updatedAt": "…"
}
Статусы: PENDING (ждёт подписи оператора шлюза) → SIGNED (отправлено в сеть, txid заполнен —
итоговый успех) | REJECTED (отклонено оператором, резерв возвращён на баланс) | FAILED
(не исполнилось в сети, резерв возвращён; reason — причина). SIGNED, REJECTED, FAILED —
конечные.
GET /v1/payouts?cursor=
GET /v1/payouts/{userId}/{idempotencyKey}
Автоматический вывод: подпись поручения (TRON, подготовка)
Чтобы выплата могла уйти без ручного подтверждения, ваш сервер подписывает поручение своим ключом Ed25519. KosPay этот ключ не получает: открытый ключ вы передаёте владельцу шлюза, он ставит его на подписанты выплат. Поэтому даже при взломе KosPay никто не сможет выписать выплату от вашего имени или подменить адрес и сумму. Без подписи выплата идёт как раньше, на ручное подтверждение. Пока принимается только для сети TRON; автоподписание ещё не включено.
В POST /v1/payouts добавьте поле:
"authorization": { "expiresAt": 1763000000000, "signature": "<Ed25519, base64, 88 символов>" }
Подписываются байты UTF-8 строки:
KOSPAY-PAYOUT-INTENT:v1:["<slug мерчанта>","<userId>:<idempotencyKey>","TRON","<to>","<amountRaw к получению>",<expiresAt>]
- массив ровно в таком виде, как его даёт
JSON.stringify, без пробелов; amountRawздесь сумма к получению, после комиссии: полеamountRawизGET /v1/payouts/quote(в запросеPOST /v1/payoutsвы по-прежнему передаёте запрошенную сумму);toровно та строка, что в запросе;expiresAtв миллисекундах Unix, от 1 минуты до 24 часов вперёд.
Node.js:
const { sign } = require('node:crypto');
const text = 'KOSPAY-PAYOUT-INTENT:v1:' + JSON.stringify([slug, `${userId}:${idempotencyKey}`, 'TRON', to, netAmountRaw, expiresAt]);
const signature = sign(null, Buffer.from(text), privateKey).toString('base64');
Python (cryptography):
import json, base64
text = 'KOSPAY-PAYOUT-INTENT:v1:' + json.dumps([slug, f'{user_id}:{key}', 'TRON', to, net_amount_raw, expires_at], separators=(',', ':'))
signature = base64.b64encode(private_key.sign(text.encode())).decode()
Шлюз проверяет только форму поля (400 при ошибке). Саму подпись проверяют подписанты: если
комиссия изменилась между расчётом и заявкой, подпись не совпадёт и выплата не уйдёт
автоматически. Храните закрытый ключ только на сервере, который создаёт выплаты.
Вебхуки
URL задаётся в кабинете («Вебхуки»); секрет подписи выдаётся там же (показывается один раз).
Каждое событие — POST на ваш URL:
Content-Type: application/json
X-Signature: <hex HMAC-SHA256(secret, сырое тело запроса)>
{"event": "deposit.credited", "data": {…}, "ts": 1758214253467}
Проверяйте подпись по сырому телу (до разбора JSON) и отвечайте 2xx только после того, как
обработали событие. Не-2xx или таймаут → доставка повторяется с нарастающими интервалами. Доставка
at-least-once: одно событие может прийти дважды — дедуплицируйте:
- пополнения — по
network + txid + logIndex; - выплаты — по
requestKey(илиuserId + idempotencyKey).
deposit.credited
{"event":"deposit.credited","ts":…,"data":{
"userId":"1386","paymentId":"4f965d7f-…",
"txid":"…","logIndex":0,"currency":"USDT","network":"TRON",
"amount":"10","fee":"0.2","platformFee":"0.15","merchantFee":"0.05","credited":"9.8"}}
Зачисляйте пользователю credited — сумма уже за вычетом всей комиссии ввода: fee = platformFee (шлюзу)
merchantFee(ваша надбавка из кабинета, «Настройки → Комиссии»; остаётся на вашем балансе как доход). Без надбавки в сети депозитаmerchantFee="0", аcredited— нетто после комиссии шлюза, как раньше. Сумму берите из события, а не из платежа: пользователь мог прислать больше, меньше или несколько раз — на каждую транзакцию приходит своё событие.paymentId=nullдля личных адресов и для пополнений, назначенных вручную.
payout.signed / payout.failed / payout.rejected
{"event":"payout.signed","ts":…,"data":{
"requestKey":"payout:<merchantId>:1386:withdraw-123",
"userId":"1386","status":"SIGNED","txid":"…",
"currency":"USDT","network":"TRON","amountRaw":"5000000",
"to":"T…","reason":null}}
payout.signed — деньги ушли (закрывайте заявку у себя). payout.failed / payout.rejected —
резерв уже возвращён на ваш баланс; верните средства пользователю.
webhook.test
Отправляется кнопкой «Отправить тест» в кабинете: {"merchant": "<slug>", "sentAt": "…"}. Ответьте 200.
Проверка подписи — Python
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, (signature or "").strip().lower())
Проверка подписи — Node.js
const crypto = require('crypto');
function verify(rawBody, signature, secret) {
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(expected), b = Buffer.from((signature || '').trim().toLowerCase());
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Лимиты и ошибки
- Ошибки — стандартный формат
{"statusCode": 409, "message": "…", "error": "Conflict"}. - Рейт-лимиты:
/v1/*— 20 запросов/с на IP (всплеск до 40); при превышении429. - Пагинация:
cursor=nextCursorпредыдущей страницы, по 50 записей. - Время — ISO 8601 в UTC.
Рекомендуемый сценарий интеграции
- Пользователь нажал «Пополнить» →
POST /v1/payments→ показатьaddress+ «оплатить доexpiresAt». - Пришёл
deposit.credited→ проверить подпись → дедуп поtxid+logIndex→ зачислитьcreditedпользователюuserId→ ответить200. - Пользователь запросил вывод → списать у себя →
POST /v1/payoutsс уникальнымidempotencyKey→ заявкаPENDING. - Пришёл
payout.signed→ закрыть заявку;payout.failed/payout.rejected→ вернуть пользователю. - Раз в день:
GET /v1/deposits?unassigned=1— если что-то есть, разобраться и назначить.