← KosPay, кабинетОбновлено 2026-11-16

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.

Суммы

Идентификатор пользователя

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 вебхука только для этой выплаты
}

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>]

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: одно событие может прийти дважды — дедуплицируйте:

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 (шлюзу)

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);
}

Лимиты и ошибки

Рекомендуемый сценарий интеграции

  1. Пользователь нажал «Пополнить» → POST /v1/payments → показать address + «оплатить до expiresAt».
  2. Пришёл deposit.credited → проверить подпись → дедуп по txid+logIndex → зачислить credited пользователю userId → ответить 200.
  3. Пользователь запросил вывод → списать у себя → POST /v1/payouts с уникальным idempotencyKey → заявка PENDING.
  4. Пришёл payout.signed → закрыть заявку; payout.failed/payout.rejected → вернуть пользователю.
  5. Раз в день: GET /v1/deposits?unassigned=1 — если что-то есть, разобраться и назначить.