Довідник API: перекази та чеки

Методи виплат. Переказ надсилає кошти з балансу застосунку прямо в гаманець користувача Telegram; чек — це посилання на активацію, яке ви оплачуєте заздалегідь. Загальні правила (автентифікація, конверт, суми, spend_id) — на сторінці Довідник Мерчант API.

transfer

POST /pay/api/transfer — право payouts, ліміт 30 на хвилину. Виконується миттєво й атомарно; стану «в обробці» немає.

Параметр	Тип	Обов’язковий	Значення
user_id	integer	так	Telegram ID отримувача. Отримувач має вже бути користувачем застосунку — виплата на невідомий id завершується помилкою, а не зависанням коштів
asset	string	так	код активу
amount	string	так	додатний десятковий рядок; також обмежений платформним мінімумом і максимумом на переказ (оцінка в доларовому еквіваленті за поточними курсами)
spend_id	string	так	ключ ідемпотентності, 1–64 символи, унікальний на виплату
comment	string	ні	до 1024 символів, показується отримувачу
disable_send_notification	boolean	ні	true — не сповіщати отримувача в Telegram

Результат — об’єкт переказу: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (завжди completed), created_at, completed_at.

Помилки: 404 user_not_found (отримувач ніколи не користувався застосунком), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (поза межами на переказ), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount і пара spend_id — 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — право payouts, ліміт 10 на хвилину. Розширення для масових виплат: до 100 переказів одним викликом.

Один параметр: items — масив, де кожен елемент — повний набір параметрів transfer (user_id, asset, amount, spend_id, необов’язкові comment і disable_send_notification). spend_id мають бути унікальними всередині пакета, інакше весь виклик падає з 400 duplicate_spend_id до будь-якого виконання.

Елементи виконуються незалежно, по порядку — невдалий елемент ніколи не відкочує решту. Виклик повертає HTTP 200 з ok: true, навіть коли частина елементів не пройшла, тому перевіряйте кожен:

• успіх: {"ok": true, "spend_id": "…", "result": <об’єкт переказу>}
• невдача: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} з тими самими іменами помилок, що й в одиночного transfer.

Елементи пакета ділять простір ідемпотентності з одиночними переказами: повтор усього пакета — або надсилання одного елемента окремим transfer з тим самим spend_id — відтворює результат, а не платить двічі.

getTransfers

GET /pay/api/getTransfers — право read. Фільтри: asset, transfer_ids (через кому), spend_id (точний збіг — знайдіть виплату за власним ключем), плюс offset / count. Повертає {"items": [переказ, …]}, нові першими.

createCheck

POST /pay/api/createCheck — право checks, ліміт 60 на хвилину. Створює одноразовий чек, оплачений з балансу застосунку; активувати його в гаманець може будь-який власник посилання — або лише закріплений користувач. Сума блокується в момент створення чека (у getBalance вона переходить з available до onhold).

Параметр	Тип	Обов’язковий	Значення
asset	string	так	код активу
amount	string	так	додатний десятковий рядок
pin_to_user_id	integer	ні	активувати чек може лише цей Telegram ID
pin_to_username	string	ні	активувати може лише цей @username (@ необов’язковий; ігнорується, якщо задано pin_to_user_id). Ім’я має належати наявному користувачу застосунку
spend_id	string	ні	ключ ідемпотентності (розширення) — використовуйте його

Результат — об’єкт чека: check_id, hash, asset, amount, amount_minor, bot_check_url (посилання t.me на активацію), status (active / activated), pin_to_user_id, created_at, activated_at. Активація надсилає вебхук check_activated, який вмикається за бажанням.

Помилки: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (закріплене ім’я нікому не належить), 409 insufficient_funds і пара spend_id.

deleteCheck

POST /pay/api/deleteCheck — право checks. Один параметр: check_id. Скасовує неактивований чек і повертає заблоковану суму на баланс застосунку; повертає true. Помилки: 404 check_not_found, 409 check_not_active (уже активований або видалений).

getChecks

GET /pay/api/getChecks — право read. Фільтри: asset, check_ids (через кому), status (active / activated), плюс offset / count. Повертає {"items": [чек, …]}, нові першими; видалені чеки не повертаються ніколи.