Як почати роботу з API

Створіть застосунок у Mini App, один раз скопіюйте його API-токен і починайте викликати API. Усі налаштування — у розділі Ще → Мерчант API.

Кроки

1. Відкрийте Ще → Мерчант API.
2. Заповніть поле Назва застосунку (наприклад, «Мій магазин») і, за бажанням, Webhook URL.
3. Натисніть Створити застосунок.
4. Одразу скопіюйте API-токен. Він показується один раз і більше ніколи — застосунок зберігає лише його хеш.
5. Надішліть перший запит із токеном у заголовку TgPayCrypto-API-Token.

Перший виклик

Спрямуйте клієнт на базову адресу API https://app.tgpaycrypto.com/pay/api і викличте getMe, щоб переконатися, що токен працює. getBalance повертає баланси вашого застосунку, getCurrencies — активи, які можна використовувати.

Методи читання — GET. Методи, що переміщують кошти, — createInvoice, transfer, createCheck і їхні парні delete-методи — лише POST, і це навмисно: сумам і ключам ідемпотентності не місце в логах доступу. Параметри можна передавати JSON-тілом, у form-urlencoded або query-параметрами.

Керування застосунком

Картка кожного застосунку в розділі Мерчант API показує його ID і баланс та дозволяє:

• Задати або змінити Webhook URL і зберегти його.
• Вибрати додаткові webhook-події — коли Webhook URL задано, перемикачі Додаткові webhook-події вмикають типи подій, крім invoice_paid (див. довідник вебхуків).
• Створити обмежені токени — додаткові API-токени в блоці Обмежені токени, кожен лише з вибраними правами (див. довідник API).
• Оновити токен — випускає новий токен і миттєво відкликає старий. Скористайтеся цим у разі витоку; новий токен показується один раз, як і під час створення.
• Видалити — застосунок перестає автентифікуватися, але його баланс та історія платежів зберігаються. Видалення застосунку ніколи не знищує його кошти.

Вебхуки

Якщо Webhook URL задано, застосунок надсилає на нього POST із підписаним JSON-тілом:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

Підпис — у заголовку TgPayCrypto-API-Signature (псевдонім для сумісності — Crypto-Pay-API-Signature): HMAC-SHA256 від сирого тіла з ключем SHA-256 від вашого API-токена. Перевіряйте його, перш ніж довіряти будь-чому в даних.

Доставки повторюються з експоненційною затримкою протягом тривалого часу, а update_id не змінюється між повторами — будуйте дедуплікацію на ньому й робіть обробник ідемпотентним.

invoice_paid доставляється завжди. Решта типів подій — рахунки, у яких минув строк, активовані чеки, повернення, події підписок — вмикаються перемикачами Додаткові webhook-події. Повний список, вміст подій і графік повторів — у довіднику вебхуків.

⚠️ Бережіть токен як приватний ключ

Він авторизує виплати з балансу вашого застосунку. Тримайте його на своєму сервері — ніколи в мобільному застосунку, фронтенд-бандлі чи в конфігу, який потрапляє в репозиторій. Не впевнені, чи не стався витік, — оновіть токен: оновлення миттєве й нічого не коштує. І давайте кожному серверу лише необхідне: обмежений токен без права payouts може виставляти рахунки, але ніколи не виведе ваш баланс.