Справочник API: переводы и чеки

Методы выплат. Перевод отправляет средства с баланса приложения прямо в кошелёк пользователя Telegram; чек — это ссылка на получение средств, сумма которой заранее блокируется на вашем балансе. Общие правила (аутентификация, конверт, суммы, spend_id) — на странице Справочник Merchant API.

Все три метода, выводящие деньги, подчиняются режиму выплат приложения: новое приложение платит кому угодно с самого начала; если владелец сузил режим, платить можно только получателям из списка (403 recipient_not_allowed) или никому (403 payouts_disabled). Режим задаёт владелец в мини-приложении; через API его не изменить. За что могут быть выплаты, определяют условия Merchant 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.

Ошибки: 403 payouts_disabled / 403 recipient_not_allowed (режим выплат), 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.

Ошибки: 403 payouts_disabled / 403 recipient_not_allowed (режим выплат — в режиме списка чек должен быть закреплён за пользователем из него), 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": [чек, …]}, новые первыми; удалённые чеки никогда не возвращаются.