Справочник API: счета и возвраты

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

createInvoice

POST /pay/api/createInvoice — право invoices, лимит 60 в минуту.

Параметр	Тип	Обязателен	Значение
currency_type	string	нет	crypto (по умолчанию) или fiat
asset	string	в крипто-режиме	актив счёта, например USDT. Передавайте вместо fiat
fiat	string	в фиатном режиме	фиатная валюта цены (строки is_fiat из getCurrencies)
accepted_assets	string / array	нет	только фиатный режим: активы, которыми может платить плательщик, — строка через запятую ("USDT,GRAM") или JSON-массив. Не указан — все поддерживаемые активы
amount	string	да, если не задан open_amount	положительная десятичная строка: в единицах актива в крипто-режиме, в фиате (максимум 2 знака) в фиатном
open_amount	boolean	нет	расширение, только крипто-режим: без фиксированной суммы — плательщик вводит её при оплате (пожертвования и чаевые). Нельзя вместе с amount
description	string	нет	до 1024 символов, показывается плательщику
hidden_message	string	нет	до 2048 символов, открывается плательщику только после оплаты
payload	string	нет	до 4096 символов ваших данных, возвращаются как есть в счёте и вебхуке
allow_comments	boolean	нет	разрешить плательщику комментарий (по умолчанию true)
allow_anonymous	boolean	нет	разрешить плательщику остаться анонимным (по умолчанию true)
paid_btn_name	string	нет	кнопка после оплаты: viewItem, openChannel, openBot или callback
paid_btn_url	string	нет	http(s)-адрес кнопки — обязателен, когда задан paid_btn_name
swap_to	string	нет	автоматически обменивать полученные платежи на этот актив. Обмен «по возможности»: если в момент оплаты он невозможен, платёж всё равно проходит без обмена
expires_in	integer	нет	секунды до истечения счёта, до 2678400 (31 день); не указан или 0 — срок по умолчанию. Фактический срок возвращается в expiration_date
rate_lock_seconds	integer	нет	расширение, только фиатный режим: зафиксировать на этот срок курсы конвертации, действовавшие в момент создания (см. ниже)

Описание, сообщение после оплаты и кнопка могут быть скрыты от плательщиков, пока содержимое проверяется или не одобрено. Сам счёт при этом остаётся доступным для оплаты.

Результат — и содержимое вебхука invoice_paid — это объект счёта. Его ключевые поля:

• Идентификаторы и статус: invoice_id, hash (публичный ID внутри pay_url), status (active / paid / expired), pay_url — ссылка t.me, которую вы отправляете плательщику (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url — её псевдонимы).
• Суммы: amount (номинал — в фиате у фиатного счёта, иначе в криптовалюте; null, пока счёт со свободной суммой не оплачен), amount_minor, а у оплаченных фиатных счетов paid_asset / paid_amount / paid_fiat_rate — фактически списанная криптовалюта и использованный курс.
• Комиссия: fee_asset / fee_amount, фиксируются при оплате — для учёта используйте именно их (fee и usd_rate — устаревшие псевдонимы Crypto Bot). См. комиссии и лимиты.
• Плательщик: paid_by_user_id (null, если плательщик выбрал анонимность), paid_anonymously, comment.
• Возвраты (расширение): refunded_amount / refunded_minor (накопительно) и refunded_at — ставится после полного возврата.
• Фиксация курса (расширение): rate_lock_until и rate_lock_rates — зафиксированные курсы по каждому принимаемому активу; null, если фиксация не запрашивалась.
• Параметры создания: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at — псевдоним), поля обмена (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Ошибки: 400 invalid_currency (перепутаны актив и фиат), 400 invalid_amount, 400 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required, а для запросов фиксации курса — 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (нет свежего курса по одному из принимаемых активов — повторите запрос).

Как оплачиваются счета

Плательщик платит с баланса кошелька в Mini App — мгновенно и без комиссии сети, при достаточном балансе и подтверждении платежа. Он может также оплатить счёт из внешнего кошелька: если этот способ доступен, приложение показывает депозитный адрес и срок оплаты. Депозит зачисляется в кошелёк плательщика. Для автоматической оплаты нужны депозит на этот адрес, достаточный доступный баланс, отсутствие ограничений на исходящие платежи и действующие счёт и запрос на оплату. Поздний депозит остаётся в кошельке и сам по себе не означает, что счёт оплачен. В обоих случаях вы видите одно и то же: обычный счёт со статусом paid и событие invoice_paid, если настроен Webhook URL, — никаких дополнительных параметров или полей.

У фиатного счёта криптосумма вычисляется в момент оплаты с округлением вверх до минимальной единицы выбранного актива. Из этой криптосуммы затем удерживается комиссия мерчанта. Если нет действующего зафиксированного курса или свежего курса, оплата не проходит на стороне плательщика — счёт не рассчитывается по устаревшему курсу.

Фиксация курса на фиатном счёте

Передайте rate_lock_seconds, чтобы при создании зафиксировать текущий курс каждого принимаемого актива. Пока фиксация действует, плательщик видит именно зафиксированные суммы, а платёж конвертируется по зафиксированному курсу — курсовой риск на этот срок берёте вы. Сервер корректирует запрошенный срок в пределах допустимого диапазона. Фактический срок фиксации возвращается в rate_lock_until.

Когда фиксация заканчивается, действующий счёт можно оплатить по курсу на момент оплаты. Чтобы оба срока совпали, задайте expires_in в допустимом для фиксации диапазоне и сравните expiration_date с rate_lock_until в ответе.

getInvoices

GET /pay/api/getInvoices — право read. Фильтры: asset, fiat, invoice_ids (через запятую), status (active / paid / expired — expired — расширение; active не включает счета, у которых уже истёк срок), плюс offset / count. Возвращает {"items": [счёт, …]}, новые первыми.

deleteInvoice

POST /pay/api/deleteInvoice — право invoices. Один параметр: invoice_id. Отменяет неоплаченный счёт и возвращает true. Ошибки: 404 invoice_not_found, 409 invoice_already_paid — оплаченный счёт удалить нельзя, средства уже переведены.

refundInvoice

POST /pay/api/refundInvoice — право refunds, лимит 30 в минуту. Расширение API Crypto Bot: возвращает всю фактически уплаченную криптосумму или её часть с баланса приложения плательщику, в том числе анонимному, не раскрывая его личность. Для фиатного счёта используйте paid_asset и paid_amount: при возврате фиат не пересчитывается заново.

Параметр	Тип	Обязателен	Значение
invoice_id	integer	да	оплаченный счёт
amount	string	нет	криптосумма возврата в активе исходного платежа (paid_asset для фиатного счёта). Не указана — весь невозвращённый остаток. Общая сумма частичных возвратов не может превышать исходную криптосумму платежа
spend_id	string	нет	ключ идемпотентности — используйте его, чтобы повтор после таймаута воспроизвёл результат, а не вернул деньги дважды

Результат — обновлённый объект счёта с накопительными refunded_amount / refunded_minor; refunded_at ставится после полного возврата. Статус остаётся paid. Комиссия платформы не возвращается. На балансе приложения должно хватать исходного актива платежа, даже если swap_to обменял поступление на другой актив. Каждый возврат создаёт включаемый по желанию вебхук refund_completed.

Ошибки: 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (возвращать больше нечего), 409 amount_too_big (больше невозвращённого остатка), 409 insufficient_funds, 400 invalid_amount и пара spend_id — 409 idempotency_conflict / 409 idempotency_in_progress.