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

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

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

transfer

POST /pay/api/transfer — право payouts, лимит 30 в минуту. Известный получатель получает выплату сразу. Для неизвестного username создаётся перевод со статусом pending: средства удерживаются до входа получателя в бота с этим именем. Неполученные средства возвращаются на баланс приложения после истечения 30 дней (expires_at). Прежде чем учитывать возврат, убедитесь, что статус изменился на returned. Передайте invite_url получателю сами: бот не может написать человеку, который его ещё не запускал. Итоговый статус — completed или returned; отслеживайте его через getTransfers или вебхуки transfer_completed и transfer_returned.

Параметр	Тип	Обязателен	Значение
user_id	integer	ровно одно из user_id / username	Telegram ID получателя; он уже должен быть пользователем приложения
username	string	ровно одно из user_id / username	имя получателя с @ или без; для неизвестного имени создаётся ожидающая выплата
asset	string	да	код актива
amount	string	да	положительная десятичная строка; также ограничена платформенным минимумом и максимумом на перевод (оценка в долларовом эквиваленте по текущим курсам)
spend_id	string	да	ключ идемпотентности, 1–64 символа, уникальный для каждой выплаты
comment	string	нет	до 1024 символов, показывается получателю
disable_send_notification	boolean	нет	true — не уведомлять получателя при немедленной выплате; при получении ожидающего перевода уведомление отправляется независимо от этого флага

Результат — объект перевода: transfer_id, hash, user_id, recipient_username, asset, amount, amount_minor, spend_id, comment, status (pending / completed / returned), created_at, completed_at, expires_at, invite_url. Пока новый получатель не пришёл, user_id может быть null; до завершения completed_at равен null.

Ошибки: 403 payouts_disabled / 403 recipient_not_allowed (режим выплат), 404 user_not_found (ID неизвестен или получатель недоступен), 400 invalid_recipient (некорректное имя получателя), 400 amount_too_small / 400 amount_too_big (за пределами лимитов на перевод), 409 insufficient_funds, 400 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 или username, asset, amount, spend_id, необязательные comment и disable_send_notification). spend_id должны быть уникальны внутри пакета, иначе весь вызов сразу отклоняется с 400 duplicate_spend_id и ни один элемент не исполняется. Неверная структура элемента, режим выплат или дневной лимит тоже могут привести к отказу всего запроса до первой выплаты. Для принятого запроса результаты возвращаются в result.items.

Элементы исполняются независимо, по порядку — неудавшийся элемент никогда не откатывает остальные. Вызов возвращает 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 (точное совпадение — так можно найти выплату по своему ключу), status (pending / completed / returned), плюс offset / count. Возвращает {"items": [перевод, …]}, новые первыми.

createCheck

POST /pay/api/createCheck — право checks, лимит 60 в минуту. По умолчанию создаёт одноразовый чек за счёт баланса приложения. Его может активировать любой обладатель ссылки или только указанный пользователь. Расширение recipients создаёт чек со списком получателей и отдельной суммой для каждого. Общая сумма блокируется при создании (в getBalance переходит из available в onhold). На создание чека действуют те же ограничения суммы и дневной лимит выплат, что и на переводы.

Параметр	Тип	Обязателен	Значение
asset	string	да	код актива
amount	string	если не задан recipients	положительная десятичная строка; при recipients общая сумма рассчитывается по списку
pin_to_user_id	integer	нет	активировать чек может только этот Telegram ID
pin_to_username	string	нет	активировать может только этот @username (@ необязателен; игнорируется, если задан pin_to_user_id). Имя должно принадлежать существующему пользователю приложения
spend_id	string	нет	ключ идемпотентности (расширение) — используйте его
recipients	array	нет	расширение: 1–100 элементов, в каждом user_id или username и положительная сумма amount десятичной строкой. Нельзя сочетать с закреплённым пользователем
password	string	нет	расширение: пароль для активации, до 64 символов
expires_in	integer	нет	расширение: срок в секундах; не указан или 0 — бессрочно

Результат — объект чека: check_id, hash, asset, amount, amount_minor, bot_check_url (ссылка t.me для активации), status (active / activated), pin_to_user_id, created_at, activated_at, expires_at и recipients (null для обычного чека; для списка каждый элемент содержит user_id, username, amount, amount_minor, claimed_at). Каждая активация создаёт включаемый по желанию вебхук check_activated; для списка он также содержит activated_slot. По истечении срока неполученный остаток возвращается; для чека со списком можно получать check_expired.

Текущий ответ API показывает status: "active" для любого не полностью активированного чека, в том числе просроченного. Проверяйте также expires_at: одного статуса active недостаточно, чтобы считать чек доступным для активации.

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