Справочник Merchant 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 действующих на приложение, создаются в разделе Ещё → Merchant 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`	непредвиденная ошибка сервера

Ошибки конкретных методов перечислены на их страницах.