Приймання платежів через рахунки

Рахунок — це спосіб виставити оплату користувачу Telegram. Ви створюєте його через API, надсилаєте платнику посилання, і сума зараховується на баланс вашого застосунку в момент підтвердження оплати.

Як це працює

Створіть рахунок методом createInvoice, вказавши актив і суму (або ціну у фіаті — див. нижче).
Надішліть платнику посилання з відповіді. Відкривши його, він потрапляє на екран «Оплата рахунку» в застосунку.
Він підтверджує й платить зі свого балансу — миттєво та без комісії мережі. Платник, якому не вистачає балансу, може профінансувати рахунок із зовнішнього гаманця: рахунок оплатиться автоматично, щойно надійде його переказ, а для вас це виглядає так само.
Ви отримуєте сповіщення. Спрацьовує вебхук invoice_paid, і сума потрапляє на баланс застосунку.
Виконуйте замовлення. Чекати більше нічого — платіж у цей момент остаточний.

Якщо ви віддаєте перевагу опитуванню 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 на ваш вебхук може будь-хто. Перевірте заголовок TgCryptoPay-API-Signature — HMAC-SHA256 від сирого тіла запиту з ключем SHA-256 від вашого API-токена, — перш ніж вважати платіж справжнім, і дедуплікуйте за update_id, щоб повтор доставки не відвантажив замовлення двічі.