Приём платежей через счета

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

Как это работает

1. Создайте счёт методом createInvoice, указав актив и сумму (или цену в фиате — см. ниже).
2. Отправьте плательщику ссылку из ответа. Открыв её, он попадает на экран «Оплата счёта» в приложении.
3. Он подтверждает и платит со своего баланса — мгновенно и без комиссии сети. Если баланса не хватает, плательщик может пополнить его из внешнего кошелька: счёт оплатится автоматически, когда перевод поступит, а для вас ничего не изменится.
4. Вы получаете уведомление. Срабатывает вебхук invoice_paid, и сумма попадает на баланс приложения.
5. Выполняйте заказ. Ждать больше нечего — платёж в этот момент окончателен.

Если вы предпочитаете опрашивать API, а не принимать вебхук, getInvoices возвращает ваши счета с их текущим статусом. Вебхук — более быстрый путь; опрос — запасной.

Цены в фиате

Счёт можно выставить в криптовалюте или в фиатной валюте со списком принимаемых активов. Тогда плательщик платит любым из этих активов, который у него есть, по курсу на момент оплаты. Это удобно магазину, где цены указаны в фиате.

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

Можно также задать swap_to, чтобы входящие платежи по мере поступления конвертировались в один актив, — так удобно держать баланс в стейблкоине, не обменивая ничего вручную.

Полезные параметры счёта

• description — показывается плательщику на экране «Оплата счёта».
• hidden_message — открывается плательщику только после оплаты. Так можно передать код, ключ или ссылку без отдельного канала доставки.
• payload — произвольная строка на ваше усмотрение, в вебхуке вернётся как есть. Кладите сюда ID заказа.
• expires_in — срок, после которого счёт больше нельзя оплатить.
• paid_btn_name / paid_btn_url — кнопка, которую плательщик видит после оплаты; она вернёт его в вашего бота, канал или на страницу товара.
• open_amount — без фиксированной суммы; плательщик вводит её при оплате. Подходит для пожертвований и чаевых.

Неоплаченный счёт можно отменить методом deleteInvoice.

Возвраты

refundInvoice возвращает номинальную сумму оплаченного счёта — или любую её часть — с баланса вашего приложения тому, кто его оплатил, включая анонимных плательщиков, не раскрывая, кто они. Частичные возвраты суммируются, пока не достигнут номинала; их общая сумма хранится в refunded_amount. Передавайте spend_id, чтобы повторный запрос после таймаута вернул тот же результат, а не деньги второй раз. Комиссия платформы не возвращается.

⚠️ Проверяйте подпись вебхука до выполнения заказа

Отправить POST на ваш вебхук может кто угодно. Проверьте заголовок TgPayCrypto-API-Signature — HMAC-SHA256 от сырого тела запроса с ключом SHA-256 от вашего API-токена, — прежде чем считать платёж настоящим, и дедуплицируйте по update_id, чтобы повтор доставки не отгрузил заказ дважды.