Справочник 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 — бессрочно
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, 404 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 — никаких дополнительных параметров или полей.

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

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

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

Когда фиксация истекает, счёт по-прежнему можно оплатить — он незаметно переходит на конвертацию по курсу на момент оплаты. Если счёт должен перестать действовать вместе с котировкой, задайте expires_in с тем же значением.

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 в минуту. Расширение над Crypto Bot: возвращает номинал оплаченного счёта — или его часть — с баланса вашего приложения тому, кто платил, в том числе анонимным плательщикам, не раскрывая, кто они.

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

Результат — обновлённый объект счёта с накопительными refunded_amount / refunded_minor; refunded_at ставится после полного возврата. Статус остаётся paid. Комиссия платформы не возвращается. Каждый возврат отправляет включаемый по желанию вебхук 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.