Deposit API

API ChainPay для приймання крипто-депозитів: без реєстрації та API-ключа за замовчуванням. Усі потрібні дані (callbackUrl, forwardAddress, externalReference) передаються прямо в запиті на створення адреси.

Опційно передайте x-api-key свого кабінету — тоді адреса привʼязується до акаунта і зʼявляється в кабінеті (розділ Deposits). Без ключа адреса лишається «анонімною»: лише webhook / status API.

Базовий URL

https://api.chainpay.site

Усі шляхи нижче — відносно нього, напр. повний ендпоінт створення адреси — POST https://api.chainpay.site/deposit-address. TLS обов'язковий; HTTP-запити не приймаються.

Підтримувані мережі

Інші мережі (polygon, arbitrum, solana) наразі недоступні для депозитів. Про розширення списку буде повідомлено окремо й відображено в цій таблиці.

1. POST /deposit-address

Публічний за замовчуванням — авторизація не обовʼязкова. Get-or-create: однакова комбінація (chain, token, callbackUrl, forwardAddress, externalReference) завжди повертає ту саму адресу — повторний виклик з тими самими параметрами безпечний.

Опційний заголовок x-api-key: <ключ з кабінету> привʼязує адресу до акаунта (clientId у відповіді, список у кабінеті).

curl -X POST https://api.chainpay.site/deposit-address \
  -H 'content-type: application/json' \
  -H 'x-api-key: $CHAINPAY_KEY' \
  -d '{
    "ticker": "trc20/usdt",
    "callbackUrl": "https://your-service.example.com/webhook?token=your-secret",
    "forwardAddress": "TYourOwnTronWallet...",
    "externalReference": "order-123"
  }'

Тіло запиту

{
  "ticker": "trc20/usdt",
  "callbackUrl": "https://your-service.example.com/webhook?token=your-secret",
  "forwardAddress": "TYourOwnTronWallet...",
  "externalReference": "order-123",
  "pending": false,
  "confirmations": 19,
  "multiToken": false
}

Формат ticker

• Голий нативний тікер — trx, bnb, eth (аліаси: trx→tron, bnb→bsc). Депозит нативної валюти мережі.
• protocol/token — trc20/usdt, bep20/usdt, erc20/usdt. protocol визначає мережу (trc20→tron, bep20→bsc, erc20→eth).
• Контракт замість символу — trc20/T... або bep20/0x... для токена, якого немає серед підтримуваних за символом.
• Символ, який не є підтримуваним токеном і не є явним контрактом → 400 Unknown token symbol.

Відповідь (201)

201 повертається і для новоствореної адреси, і для наявної (get-or-create).

{
  "id": "6311badc-787a-4e33-804a-9562a553e320",
  "chain": "tron",
  "tokenSymbol": "USDT",
  "tokenAddress": null,
  "isNative": false,
  "multiToken": false,
  "tokenKey": "USDT",
  "address": "THjTgKDGj3Biar7ZTSmYZAWsqkTKhWGv5Y",
  "callbackUrl": "https://your-service.example.com/webhook?token=your-secret",
  "forwardAddress": "TYourOwnTronWallet...",
  "swept": false,
  "notifyOnPending": false,
  "confirmationsRequired": 19,
  "createdAt": "2026-09-05T08:45:54.257Z"
}

address — адреса, яку показуєте платнику. Для multiToken: true поля tokenSymbol/tokenAddress дорівнюють null, а isNative — false (адреса не прив'язана до одного активу, див. §4).

Помилки (400)

• Невалідний ticker або невідомий символ токена.
• callbackUrl / forwardAddress відсутні або невалідного формату для мережі.
• callbackUrl вказує на приватну/локальну адресу.
• confirmations < 1.
• multiToken: true з не-нативним ticker.

2. GET /deposit-address/:id/status

Останній депозит для цієї адреси — резервний спосіб дізнатися стан, якщо вебхук затримався або не дійшов. 404, якщо адреси не існує.

{
  "id": "...",
  "type": "deposit",
  "chain": "tron",
  "txHash": "...",
  "status": "confirmed",
  "amount": "100.000000",
  "tokenSymbol": "USDT",
  "tokenAddress": null,
  "isNative": false,
  "blockNum": "68000000",
  "createdAt": "...",
  "confirmedAt": "..."
}

status:

• pending — депозит побачено в мережі, поріг підтверджень ще не досягнуто;
• confirmed — підтверджено й зараховано;
• dust — сума нижча за мінімальний поріг депозиту; не зараховується, форвард не виконується;
• failed — транзакцію відкинуто внаслідок реорганізації мережі.

3. GET /deposit-address/:id/transactions

Повна історія адреси — рядки депозитів і рядки форварду коштів (destination: settlement — переказ на ваш forwardAddress, destination: fee_collector — утримана комісія). Адреса персистентна й може отримати кілька депозитів за час життя.

4. Multi-token адреси (multiToken: true)

Одна адреса приймає нативну валюту мережі (TRX / BNB / ETH…) і будь-який підтримуваний токен цієї мережі (USDT, USDC), замість прив'язки до однієї валюти. Працює на TRON та EVM-мережах. На EVM переказ, надісланий смарт-контрактом (internal transfer), поки не детектиться.

{ "ticker": "trx", "multiToken": true, "callbackUrl": "...", "forwardAddress": "...", "externalReference": "..." }

Кожен депозит на таку адресу може бути іншим активом, тому у відповіді на створення адреси tokenSymbol/tokenAddress/isNative завжди null/null/false. Конкретний актив кожного депозиту дивіться у вебхуці або в GET /deposit-address/:id/transactions — кожен рядок несе власні tokenSymbol / isNative.

Токен, який не входить до списку підтримуваних, не зараховується навіть на multi-token адресу.

5. Вебхуки на callbackUrl

Вебхуки не підписуються HMAC. Верифікація джерела — на вашому боці, двома способами (рекомендуємо застосувати обидва):

1. Секретний токен у callbackUrl. Додайте власний секрет у query-рядок при створенні адреси (https://your-service.example.com/webhook?token=...) — ми надсилаємо вебхук саме на цей URL, з токеном. Звіряйте його на своєму боці. Це основний механізм.

2. IP-адреса відправника. Усі вебхуки надходять з фіксованої IP-адреси нашого сервера:

157.180.64.58

(один IPv4, без діапазону; вебхуки йдуть напряму з сервера, не через CDN/проксі). Занесіть її в allow-list на своєму ендпоінті. Про зміну IP — завчасне повідомлення й оновлення цього рядка; тому не покладайтесь тільки на IP — токен із п.1 має лишатись обов'язковим.

Content-Type: application/json, метод POST, тіло — JSON нижче.

pending (лише якщо pending: true при створенні)

Надсилається одразу після виявлення депозиту в мережі, до фінальності:

{
  "status": "pending",
  "externalReference": "order-123",
  "chain": "tron",
  "tokenSymbol": "USDT",
  "tokenAddress": null,
  "isNative": false,
  "amount": "100.000000",
  "txHash": "8a3fb315..."
}

confirmed

TRON — надсилається після того, як форвард коштів виконано, з повним результатом:

{
  "status": "confirmed",
  "externalReference": "order-123",
  "chain": "tron",
  "tokenSymbol": "USDT",
  "tokenAddress": null,
  "isNative": false,
  "amount": "100.000000",
  "txHash": "8a3fb315...",
  "fee": "5.3",
  "valueForwarded": "94.7",
  "txidOut": "c665fba0..."
}

• amount / txHash — сума й хеш вхідного депозиту (до комісії).
• fee — утримана комісія (в одиницях токена депозиту).
• valueForwarded — сума, надіслана на ваш forwardAddress (amount − fee).
• txidOut — хеш вихідної транзакції на forwardAddress.

EVM-чейни (bsc, eth) — надсилається одразу при досягненні порогу підтверджень, без полів fee / valueForwarded / txidOut:

{
  "status": "confirmed",
  "externalReference": "order-123",
  "chain": "bsc",
  "tokenSymbol": "USDT",
  "tokenAddress": null,
  "isNative": false,
  "amount": "100.000000",
  "txHash": "0x..."
}

amount чи valueForwarded — що зараховувати на баланс користувача

Це ваш вибір:

• amount — сума, яку фактично надіслав покупець (до нашої комісії).
• valueForwarded — сума, яку ви реально отримали на forwardAddress (amount − fee, тобто вже за вирахуванням нашої комісії).

Якщо зараховуєте valueForwarded, комісія лягає на покупця (він поповнить рівно на стільки, скільки надіслав, а баланс отримає менше). Якщо зараховуєте amount, комісію бере на себе клієнт (покупець бачить повну суму на балансі, різницю покриваєте ви). Обидва підходи коректні — це питання того, хто в вашій бізнес-моделі покриває комісію.

Для EVM-чейнів (bsc, eth), де в confirmed-вебхуці немає полів fee / valueForwarded, точні значення доступні через GET /deposit-address/:id/transactions.

Випадки без confirmed-вебхука

Якщо депозит виявився нижчим за мінімальний поріг (dust), confirmed-вебхук не надсилається. Дізнатися про такий депозит можна через GET /deposit-address/:id/status (статус dust).

Доставка й ретраї

Exponential backoff (30 с → до 1 год), до 8 спроб. Можливе повторне надсилання того самого вебхука — забезпечте ідемпотентність на своєму боці за txHash / txidOut.

6. Типовий інтеграційний цикл

1. Користувач хоче поповнити баланс → POST /deposit-address з унікальним externalReference → покажіть йому address.
2. Користувач надсилає кошти на цю адресу.
3. (Опційно, якщо pending: true) отримуєте pending-вебхук — показуєте «очікує підтвердження».
4. Отримуєте confirmed-вебхук → зараховуєте amount або valueForwarded на баланс користувача (ваш вибір, хто покриває комісію — див. розділ 5).
5. Якщо вебхук не прийшов за розумний час → фолбек на GET /deposit-address/:id/status.