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

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

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

Создайте счёт методом createInvoice, указав актив и сумму (или цену в фиате — см. ниже).
Отправьте плательщику ссылку из ответа. Открыв её, он попадает на экран «Оплата счёта» в приложении.
Он подтверждает и платит со своего баланса — мгновенно и без комиссии сети. Если баланса не хватает, плательщик может пополнить его из внешнего кошелька, если этот способ доступен. Для автоматической оплаты нужны достаточный зачисленный баланс до окончания срока оплаты и отсутствие ограничений на исходящие платежи. Сам депозит ещё не подтверждает оплату счёта.
Вы получаете уведомление. Если настроен Webhook URL, после оплаты событие invoice_paid ставится в очередь доставки. На баланс приложения поступает сумма за вычетом комиссии.
Выполняйте заказ. Сначала проверьте подпись вебхука, сопоставьте счёт с заказом и убедитесь, что статус — paid. Статус можно проверить через getInvoices; дополнительных подтверждений блокчейна ждать не нужно.

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

Цены в фиате

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

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

Можно также задать swap_to, чтобы входящие платежи по мере поступления конвертировались в один актив, когда обмен доступен. Если обмен провести нельзя, платёж всё равно проходит в исходном активе. Проверяйте is_swapped и поля swapped_*.

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

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

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

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

Возвраты

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

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

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