Документація API

Кому це потрібно. Якщо ви стример і просто приймаєте донати, API вам не знадобиться, усе є в кабінеті. Ця сторінка для тих, хто вбудовує оплату у свій сайт або бот.

Як це влаштовано

Ви створюєте інвойс, а ми віддаємо адресу та посилання на сторінку оплати. Далі ми самі стежимо за блокчейном і, коли платіж набере потрібну кількість підтверджень, надсилаємо вам webhook. Гроші при цьому йдуть напряму на ваш гаманець: ми їх не тримаємо і не можемо затримати.

Автентифікація

Ключ створюється в кабінеті й показується один раз. Передається заголовком:

X-Api-Key: pk_xxxx.yyyy

Ключ це доступ до створення інвойсів від вашого імені. Тримайте його на сервері. Не кладіть у код сторінки, у мобільний застосунок і в публічний репозиторій. Витік, відкличте в кабінеті, старий ключ перестане працювати одразу.

Створити інвойс

POST /v1/invoices
X-Api-Key: pk_xxxx.yyyy
Content-Type: application/json

{
  "currency": "BTC",
  "type": "order",
  "expected_amount": "150000",
  "order_id": "order-42"
}

Суми всюди рядком і в мінімальних одиницях (сатоші для BTC, літоші для LTC). Не число з рухомою комою: 0.1 + 0.2 у більшості мов дає не 0.3, а на грошах це неприпустимо.

Заголовок Idempotency-Key захищає від дублів: повтор того самого запиту поверне той самий інвойс, а не створить другий. Те саме робить унікальний order_id.

Webhook

Надходить на вашу адресу за подіями invoice.confirmed, invoice.expired, invoice.underpaid та invoice.late_payment. Підписаний HMAC-SHA256 вашим секретом.

Перевіряйте підпис за сирим тілом запиту, до розбору JSON. Якщо спершу розібрати, а потім зібрати назад, байти зміняться і підпис не зійдеться. Робочий приклад із перевіркою підпису та захистом від повторів лежить у репозиторії: examples/webhook-receiver.mjs.

Статус pending у webhook не надходить навмисно: це ще не гроші, а лише помічена транзакція. Для живого відображення є SSE на сторінці оплати.

Повна специфікація

Машиночитана схема OpenAPI 3.0 з усіма маршрутами, полями та кодами помилок:

openapi.yaml — файл специфікації. Його можна відкрити у Swagger Editor, Postman, Insomnia або згодувати генератору клієнта для вашої мови.

Якщо відкрити посилання просто в браузері, ви побачите текст YAML, так і має бути: це формат для інструментів, а не для читання очима.