Довідник Мерчант API

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

API сумісний з Crypto Bot: наявна інтеграція з Crypto Bot працює після заміни лише базової адреси й токена. Усе, що виходить за межі цього контракту, позначено нижче словом розширення.

Поряд із цими сторінками опубліковано машиночитану специфікацію OpenAPI 3.1 усього API — кожен метод, об’єкт, ім’я помилки та вебхук: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Подавайте її в генератори коду, API-клієнти та ШІ-інструменти.

Базова адреса й автентифікація

Усі методи доступні за адресою https://crypto.tgpaybot.com/pay/api/<methodName>.

Кожен запит автентифікується токеном у заголовку TgCryptoPay-API-Token (Crypto-Pay-API-Token приймається як псевдонім для сумісності; якщо надіслано обидва, виграє канонічний). Відсутній, неправильний або відкликаний токен — а також токен видаленого застосунку — повертає 401 unauthorized.

Токен має вигляд <app_id>:<secret> і показується один раз — під час створення або оновлення; сервер зберігає лише його хеш. Див. Як почати роботу з API.

Токени та права

Однаково автентифікуються два види ключів:

Основний токен — повний доступ до всіх методів і єдиний ключ, яким підписуються вебхуки.
Обмежені токени (розширення) — до 10 чинних на застосунок, створюються в розділі Ще → Мерчант API у блоці Обмежені токени, кожен із назвою та набором прав. Відкликання миттєве й не зачіпає інші; оновлення основного токена їх теж не зачіпає.

Право	Які методи відкриває
(будь-який чинний токен)	`getMe`, `getCurrencies`, `getExchangeRates`
`read`	`getBalance`, `getStats`, `getInvoices`, `getChecks`, `getTransfers`, `getSubscriptionPlans`, `getSubscriptions`
`invoices`	`createInvoice`, `deleteInvoice`
`refunds`	`refundInvoice`
`payouts`	`transfer`, `transferBatch`
`checks`	`createCheck`, `deleteCheck`
`subscriptions`	`createSubscriptionPlan`, `archiveSubscriptionPlan`, `cancelSubscription`

Права незалежні та складаються — invoices не включає read, тому сервер, який лише виставляє рахунки, може тримати токен, що не вміє нічого читати. Виклик методу, не покритого токеном, повертає 403 scope_required. getMe повідомляє права поточного токена (scopes; null — основний токен) і його назву (token_name), тож завжди можна перевірити, що у вас у руках.

Запити та відповіді

Методи читання — GET з параметрами в query-рядку. Методи, що переміщують кошти, — лише POST: параметри JSON-тілом, form-urlencoded або query-параметрами (у разі конфлікту виграє тіло); multipart/form-data не підтримується.
Кожна відповідь — JSON в одному конверті: успіх {"ok": true, "result": …}, помилка {"ok": false, "error": {"code": <HTTP-статус>, "name": "<ім’я_помилки>"}}. Розгалужуйтеся за error.name — це стабільний машиночитаний рядок.
Один крайній випадок: query-значення неправильного типу в GET-методі (наприклад, offset=abc) повертає HTTP 422 з тілом {"detail": …} поза конвертом. Передавайте коректно типізовані query-значення.

Суми

Криптосуми — десяткові рядки в цілих одиницях активу ("10.5"), ніколи не JSON-числа. У відповідях додатково є amount_minor (розширення): ціла сума в мінорних одиницях рядком, бо значення масштабу wei переповнюють Number у JavaScript.
decimals кожного активу беріть із getCurrencies — будуйте арифметику на цих даних, а не на зашитій таблиці.
Фіатні суми — щонайбільше 2 десяткові знаки.
Курси — рядки з фіксованою крапкою, ніколи не числа.

Пагінація

Списочні методи (getInvoices, getChecks, getTransfers, getSubscriptions) приймають offset (за замовчуванням 0) і count (за замовчуванням 100, максимум 1000; у getSubscriptions — 500) і повертають {"items": […]}, нові першими. Фільтри за id (invoice_ids, check_ids, transfer_ids) — цілі числа через кому. Усі позначки часу — рядки ISO 8601.

Ідемпотентність: `spend_id`

Методи, що переміщують кошти, приймають ключ spend_id, який генеруєте ви (1–64 символи): обов’язковий у transfer і в кожному елементі transferBatch, необов’язковий у createCheck і refundInvoice (розширення — використовуйте все одно). Повтор із тим самим ключем і тими самими параметрами відтворює початковий результат, а не рухає кошти вдруге, тому запит, що впав за тайм-аутом, завжди безпечно повторити. Той самий ключ з іншими параметрами повертає 409 idempotency_conflict; повтор, поки початковий запит ще виконується, — 409 idempotency_in_progress.

Ліміти запитів

На застосунок, спільні для всіх його токенів; перевищення повертає 429 rate_limited:

Метод	Ліміт
`createInvoice`, `createCheck`	60 на хвилину
`refundInvoice`, `transfer`	30 на хвилину
`transferBatch`	10 на хвилину

Методи читання не обмежені. Під час технічних робіт методи запису повертають 503 maintenance, читання продовжує працювати.

Методи каталогу та акаунта

getMe

GET /pay/api/getMe — без параметрів. Повертає дані застосунку: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (додаткові типи вебхуків, на які підписано застосунок) і описані вище поля токена scopes / token_name.

getBalance

GET /pay/api/getBalance — без параметрів. Повертає масив із рядком на кожен підтримуваний актив, навіть нульовий: currency_code, available (доступний баланс), onhold (кошти, заблоковані у ваших непогашених чеках) і amount_minor.

getCurrencies

GET /pay/api/getCurrencies — без параметрів. Авторитетний список того, що підтримує API: крипторядки (is_blockchain: true) і фіатні валюти, у яких можна виставляти рахунки (is_fiat: true). У кожному рядку — code, name, decimals і прапорець is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — без параметрів. Котирування криптовалюта→фіат: source, target, rate (рядок з фіксованою крапкою) і is_valid — false означає, що вся таблиця віддана із застарілого кешу; вважайте такі курси орієнтовними.

getStats

GET /pay/api/getStats — необов’язкові start_at / end_at (ISO 8601; вікно за замовчуванням — останні 24 години). Повертає volume (вартість оплачених рахунків за вікно в USD), conversion (відсоток оплачених від створених), unique_users_count, created_invoice_count, paid_invoice_count і фактичні межі вікна. Дата в нерозпізнаному форматі повертає 400 invalid_date.

Помилки, можливі в будь-якому методі

HTTP	`error.name`	Коли
401	`unauthorized`	відсутній, неправильний або відкликаний токен
403	`scope_required`	у токена немає права на метод
400	`invalid_request`	параметри, які не вдалося розібрати, або неправильні (POST)
429	`rate_limited`	перевищено ліміт запитів
503	`maintenance`	технічні роботи (методи запису)
500	`internal_error`	непередбачена помилка сервера

Специфічні помилки перелічені на сторінці кожного методу.