Довідник API: рахунки та повернення

Методи рахунків: createInvoice, getInvoices, deleteInvoice, refundInvoice. Загальні правила (автентифікація, конверт, суми, spend_id) — на сторінці Довідник Мерчант 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.