Справочник Merchant API

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

API совместим с Crypto Bot: существующая интеграция с Crypto Bot работает после замены только базового адреса и токена. Всё, что выходит за рамки этого контракта, помечено ниже словом расширение.

Рядом с этими страницами опубликована машиночитаемая спецификация OpenAPI 3.1 всего API — каждый метод, объект, имя ошибки и вебхук: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Её можно отдать генераторам кода, API-клиентам или ИИ-инструментам.

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

Все методы доступны по адресу https://app.tgpaycrypto.com/pay/api/<methodName>. В тестовой сети базовый адрес — https://testnet.tgpaycrypto.com/pay/api: отдельные приложения и токены, монеты без стоимости.

Каждый запрос аутентифицируется токеном в заголовке TgPayCrypto-API-Token (прежнее имя 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), так что всегда можно проверить, что у вас в руках.

Режим выплат

Право отвечает за то, какие методы доступны токену; режим выплат приложения — за то, кому любой из его токенов, включая основной, может платить. Новое приложение платит кому угодно с первой минуты; владелец может сузить это в разделе Ещё → Merchant API → Выплаты через API как защиту на случай утечки токена, так же, как дневной лимит. Чтобы снова расширить, нужен PIN-код или Face ID; API может лишь прочитать режим (getMe → payout_mode).

payout_mode	Что могут transfer, transferBatch и createCheck
any	платить любому пользователю, оставлять выплату для неизвестного @username в эскроу, создавать чеки на предъявителя — так по умолчанию, это поведение Crypto Bot
allowlist	платить только пользователям Telegram из списка получателей приложения. Все остальные, неизвестный @username (без эскроу) и чек, не закреплённый за пользователем из списка, получают 403 recipient_not_allowed
off	ничего — любой вызов выплаты возвращает 403 payouts_disabled; счета, подписки, возвраты и вебхуки работают как обычно

Об отклонённой выплате владелец получает уведомление в Telegram и может изменить режим. Дневной лимит выплат действует поверх режима. За что можно платить, определяют условия Merchant API.

Запросы и ответы

• Методы чтения — 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 и payout_mode (off / allowlist / any).

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	у токена нет права на метод
403	payouts_disabled	режим выплат приложения — off (только методы выплат)
403	recipient_not_allowed	получателя нет в списке приложения (только методы выплат)
400	invalid_request	нераспознанные или неверные параметры (POST)
429	rate_limited	превышен лимит запросов
503	maintenance	технические работы (методы записи)
500	internal_error	непредвиденная ошибка сервера

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