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

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

API использует соглашения Crypto Bot для описанных здесь методов. Замените базовый адрес и токен, затем проверьте используемые методы в тестовой сети. Наши дополнения помечены ниже словом расширение.

Также доступна машиночитаемая спецификация OpenAPI 3.1: 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, использовавшееся до 2026-09-07, и 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
webhooks	updateApp

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

Режим выплат

Право отвечает за то, какие методы доступны токену; режим выплат приложения — за то, кому любой из его токенов, включая основной, может платить. Новое приложение платит кому угодно с первой минуты; владелец может ограничить круг получателей: в разделе Ещё → Merchant API откройте приложение, затем Настройки выплат → Выплаты через API. Как и дневной лимит, эта настройка ограничивает возможности того, кто получил доступ к токену. Чтобы снова расширить круг получателей, нужен PIN или биометрия; 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 не поддерживается. Тело с любым другим Content-Type (text/plain или без заголовка) игнорируется — читаются только query-параметры. Параметры-массивы (transferBatch.items, createCheck.recipients) работают только в JSON-теле.
• Ответы обработчиков API имеют общий формат JSON: успех {"ok": true, "result": …}, ошибка {"ok": false, "error": {"code": <HTTP-статус>, "name": "<имя_ошибки>"}}. Обрабатывайте ошибки по error.name — это стабильная машиночитаемая строка.
• Query-параметр неверного типа в GET-методе (например, offset=abc) может быть отклонён до запуска обработчика API. Проверяйте HTTP-статус: ответ с ошибкой не всегда имеет указанный выше формат. Передавайте query-параметры ожидаемых типов.

Суммы

• Суммы в криптовалюте — десятичные строки в основных единицах актива ("10.5"), никогда не JSON-числа, в том числе в запросах: {"amount": 10.5} вернёт 400 invalid_request, отправляйте {"amount": "10.5"}. То же относится к любому строковому параметру (asset, spend_id, comment и т. д.).
• Сумма с бо́льшим числом знаков после запятой, чем у актива, округляется до точности актива по правилам арифметики, а не отклоняется; сумма, которая округляется до нуля, возвращает 400 invalid_amount.
• В ответах дополнительно есть 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 (расширение — используйте всё равно). У transfer и элементов transferBatch общее пространство ключей. Повтор с тем же ключом и теми же параметрами воспроизводит исходный результат, а не переводит средства второй раз, поэтому запрос, упавший по таймауту, всегда безопасно повторить. Тот же ключ с другими параметрами возвращает 409 idempotency_conflict; повтор, пока исходный запрос ещё выполняется, — 409 idempotency_in_progress. Запрос, завершившийся ошибкой 4xx, ключ не расходует: повтор с тем же ключом выполнит его заново.

Лимиты запросов

Лимиты устанавливаются на приложение и распространяются на все его токены; у каждого метода свой счётчик. При превышении — 429 rate_limited:

Метод	Лимит
createInvoice, createCheck	60 в минуту
refundInvoice	30 в минуту
transfer	30 в минуту
transferBatch	10 в минуту
updateApp	10 в минуту
createSubscriptionPlan	20 в минуту

Ещё два лимита защищают от перебора:

• Неудачная аутентификация: после 30 запросов с отсутствующим или неверным токеном с одного IP-адреса за минуту все запросы с этого адреса получают 429 rate_limited до конца минуты — в том числе с верным токеном. Не запускайте неправильно настроенные задачи с того же IP, что и рабочий трафик.
• Неизвестные получатели: после 10 обращений к несуществующему user_id или @username в одном приложении за минуту (transfer, элементы transferBatch, createCheck с pin_to_username) любой поиск получателя в этом приложении возвращает 429 rate_limited до конца минуты.

Могут действовать дополнительные ограничения запросов. При 429 rate_limited увеличивайте паузу перед повторной попыткой. Во время технических работ методы записи возвращают 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), daily_payout_max_usd_cents (0 — лимит владельцем не задан) и daily_payout_spent_usd_cents (расход за последние 24 часа).

updateApp

POST /pay/api/updateApp — право webhooks. Необязательные параметры: name (1–64 символа), webhook_url (публичный HTTPS-адрес длиной до 256 символов; пустая строка удаляет его) и webhook_events (массив или список имён поддерживаемых дополнительных событий через запятую). Пустой список событий оставляет только invoice_paid. Возвращает те же поля приложения, что и getMe.

Ошибки: 400 invalid_request (длина name — меньше 1 или больше 64 символов, или webhook_url — не публичный HTTPS-адрес либо длиннее 256 символов), 400 invalid_name (имя похоже на ссылку или @username), 400 app_name_reserved (в имени используется название TgPay Crypto) и 400 invalid_webhook_events (неизвестное имя события — в том числе invoice_paid: его не нужно включать отдельно).

getBalance

GET /pay/api/getBalance — без параметров. Возвращает массив со строкой на каждый поддерживаемый актив, даже с нулевым балансом (отключённый актив показывается, только пока он есть на балансе приложения): currency_code, available (доступный баланс), onhold (неполученные средства в чеках и ожидающие выплаты по @username) и 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, is_crypto и is_fiat. Эти курсы — ориентировочные: is_valid: true не гарантирует, что котировка актуальна. Если получить курсы не удалось, результат может быть пустым массивом. Для сверки фактического платежа используйте суммы и курсы, записанные в оплаченном счёте.

getStats

GET /pay/api/getStats — необязательные start_at / end_at (ISO 8601; окно по умолчанию — последние 24 часа). Возвращает volume (оценка оплаченных за период счетов в USD по текущим курсам; активы без курса учитываются как ноль), conversion (процент оплаченных от созданных), unique_users_count, created_invoice_count, paid_invoice_count и фактические границы окна. volume и conversion — JSON-числа, а не строки. Нераспознанная дата возвращает 400 invalid_date.

Ошибки, возможные в любом методе

HTTP	error.name	Когда
401	unauthorized	отсутствующий, неверный или отозванный токен
403	scope_required	у токена нет права на метод
403	payouts_disabled	режим выплат приложения — off (только методы выплат)
403	recipient_not_allowed	получателя нет в списке приложения (только методы выплат)
400	invalid_request	нераспознанные или неверные параметры (POST)
403	daily_cap_exceeded	будет превышен дневной лимит выплат приложения
403	verification_required	исходящие операции владельца ограничены; затрагивает переводы, чеки и возвраты
503	merchant_payouts_paused	списания с баланса приложения временно приостановлены
429	rate_limited	превышен лимит запросов
503	maintenance	технические работы (методы записи)
500	internal_error	непредвиденная ошибка сервера

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

Ошибки без JSON-ответа

По одному лишь текстовому или HTML-ответу нельзя определить, на каком уровне возникла ошибка. Проверьте HTTP-статус, тело и заголовки ответа.

Если Cloudflare возвращает error code: 1010, он отклонил клиент по сигнатуре браузера до того, как запрос дошёл до API. Права токена не являются причиной этой ошибки Cloudflare. Отсутствующий или нестандартный User-Agent может вызвать срабатывание сетевой защиты. Попробуйте указать заголовок User-Agent с названием вашего клиента, например MyShop/1.0, и повторите запрос; это не гарантирует устранения ошибки. Если она сохраняется, отправьте в поддержку HTTP-статус, тело и заголовки ответа, удалив токены и cookies.