API криптовалютного платежного шлюза: 12 пунктов, которые нужно проверить до интеграции
Любой API для приёма криптовалюты умеет создать счёт. Различия видны при повторных запросах, частичных оплатах и сбоях вебхуков. Чек-лист из 12 пунктов для разработчиков — и как API mistKET закрывает каждый из них.
Любой API криптовалютного платёжного шлюза обещает одно и то же: создать счёт, получить оплату, принять callback. Разница проявляется позже — когда два запроса приходят одновременно, когда клиент отправляет чуть меньше суммы счёта, когда ваш сервер час недоступен или когда злоумышленник повторяет перехваченный запрос. Тщательный выбор API экономит гораздо больше времени, чем быстрая интеграция.
Это чек-лист для разработчиков и CTO, которые сравнивают API для приёма криптовалюты до того, как написать первую строку кода. Для каждого пункта — на что смотреть, почему это важно и как это устроено в API mistKET. Если вы уже сделали выбор и вам нужен пошаговый код, переходите к нашему руководству по интеграции крипто платёжного API.
Минимальный набор эндпоинтов
Рабочему API для приёма криптоплатежей нужно больше, чем «создать платёж». Как минимум ищите:
| Возможность | Зачем она нужна | Эндпоинт mistKET |
|---|---|---|
| Создание счёта | Один запрос на оплату на каждый заказ, со сроком действия | POST /invoices |
| Получение счёта | Сверка, если вебхук не дошёл | GET /invoices/{uuid} |
| Список и фильтрация счетов | Экраны бэк-офиса и ночная сверка | GET /invoices |
| Отмена счёта | Вернуть товар в остаток, если заказ брошен | POST /invoices/{uuid}/cancel |
| Поддерживаемые активы | Показывать только сети, которыми можно заплатить прямо сейчас | GET /assets |
| Котировка курса | Показать сумму в криптовалюте до создания счёта | GET /rate |
| Проверка состояния | Мониторинг и корректный запасной сценарий | GET /health |
Если провайдер не умеет отдавать счёт или список счетов, вам придётся слепо доверять вебхукам — плохая позиция в тот момент, когда первая доставка не пройдёт.
1. Аутентификация: подписан ли каждый запрос?
API-ключ в заголовке — самый слабый вариант: любой, кто перехватит его или получит при утечке, сможет создавать и отменять счета. Выбирайте API, где каждый запрос подписывается секретом, который никогда не передаётся по сети. Запросы к mistKET содержат X-Api-Key, X-Api-Timestamp и подпись HMAC-SHA256 от метки времени и сырого тела запроса. Секрет показывается в панели мерчанта только один раз.
2. Защита от повторной отправки (replay)
Сама по себе подпись не мешает повторно отправить перехваченный запрос. Ищите окно допустимых меток времени и поддержку nonce. mistKET отклоняет метки времени, которые расходятся с серверным временем больше чем на ±300 секунд, и не принимает одну и ту же подпись дважды для запросов, меняющих состояние. Версия подписи 2 добавляет nonce для каждого запроса и подписывает также метод и путь, поэтому подпись нельзя использовать на другом эндпоинте.
3. Идемпотентность при создании счёта
Сетевые запросы падают по таймауту. Если ваш checkout повторяет вызов «создать счёт», у одного заказа не должно появиться двух счетов. Хороший API предлагает ключ идемпотентности. В mistKET эту роль играет ваш собственный order_id: повторный вызов с тем же ID заказа возвращает существующий счёт с "idempotent": true вместо создания нового.
4. Модель статусов, которая покрывает реальные платежи
«Оплачено / не оплачено» — этого недостаточно. Клиенты отправляют чуть меньше, потому что биржа удержала комиссию, или больше, или платят после истечения срока. Проверьте, что API явно показывает эти случаи. Счета mistKET проходят статусы new, pending, underpaid, paid, confirmed, overpaid, expired и cancelled, а поля paid_amount, remaining_amount, can_pay_remaining и under_review избавляют ваш код от догадок.
paid означает, что перевод обнаружен и ждёт подтверждений; выполняйте заказы только при confirmed или overpaid.5. Подтверждения, которые видно
API должен сообщать, сколько подтверждений блоков у платежа и сколько требуется, а также хеш транзакции и ссылку на обозреватель блоков. Тогда обращения в поддержку по платежам решаются быстрой проверкой. mistKET возвращает для каждого счёта confirmations, required_confirmations и массив transactions[] с хешем, суммой, статусом и URL обозревателя.
6. Фиксация курса и валюты цен
Вы назначаете цену в фиате, клиент платит в криптовалюте. Уточните, какие фиатные валюты поддерживаются и как долго держится курс. mistKET принимает цены в USD, EUR, TRY, RUB, GBP и AED (или сразу в символе криптовалюты), фиксирует курс на всё время жизни счёта и позволяет задать это время от 5 до 1440 минут для каждого счёта.
7. Выбор сети
Можно ли зафиксировать сеть в вызове API или дать клиенту выбрать её на платёжной странице? Полезны оба варианта: фиксация подходит ботам и автоматическим сценариям, а выбор клиентом сокращает число платежей не в ту сеть. mistKET поддерживает оба через pay_currency + network или asset_id, а GET /assets возвращает available: false, если в сети нет свободного адреса. Сегодня включён USDT в сети TRON (TRC-20); другие активы и сети включаются для мерчанта по запросу. Почему TRON — привычный вариант по умолчанию, читайте в статье USDT TRC20 и ERC20.
8. Подписанные, повторяемые и отслеживаемые вебхуки
Именно на вебхуках ломается большинство интеграций. Проверьте четыре вещи: payload подписан, есть метка времени для отклонения устаревших доставок, неудачные доставки повторяются часами (а не секундами), и у каждой доставки есть ID для дедупликации. mistKET подписывает вебхуки отдельным секретом вебхука, отправляет заголовки X-Mistket-Delivery и X-Mistket-Event и при ответах не 2xx повторяет доставку через 10 с, 30 с, 2 мин, 10 мин, 30 мин, 1 ч, 2 ч и 3 ч; история доставок видна в панели. Подробно о проектировании обработчика — в нашей статье о вебхуках криптоплатежей.
9. Задокументированные ошибки и лимиты
Вы должны заранее знать, как выглядит ответ при неверной подписи, заблокированном IP или ошибке валидации. mistKET возвращает единообразное тело { "success": false, "error": … } с деталями по каждому полю для ошибок валидации, использует стандартные коды (401, 403, 404, 422, 429, 503) и документирует свой лимит: 120 запросов в минуту на API-ключ.
10. Контроль на уровне сети
Белый список IP делает утёкший ключ бесполезным везде, кроме ваших серверов. В mistKET его можно задать в панели; запросы с других адресов получают 403. Вместе с подписанными запросами и коротким окном меток времени это закрывает самые распространённые векторы атак.
11. Никакой привязки к SDK
SDK удобны, пока не начинают отставать от версии вашего языка. API на обычном HTTPS и JSON, где подпись — это один вызов HMAC, работает из PHP, Node.js, Python, Go или shell-скрипта. mistKET публикует готовые клиенты для PHP, Node.js и Python в своей документации API, но ни один из них не обязателен.
12. Ручной сценарий для неразработчиков
Даже бизнесу, построенному вокруг API, иногда нужно выставить разовый счёт клиенту. Проверьте, что счета можно создавать и в панели и отправлять ссылкой, чтобы отделу продаж и поддержке не приходилось звать разработчиков. В mistKET те же счета доступны в панели мерчанта, а каждая платёжная страница работает как платёжная ссылка.
GET /invoices/{uuid} и сравните. Так за один проход проверяются подпись, обработчик вебхуков и сверка.Тревожные признаки при выборе API для приёма криптовалюты
- Неподписанные вебхуки или вебхуки, «защищённые» только секретным URL.
- Нельзя получить счёт после создания.
- Нет статусов underpaid и overpaid — пограничные случаи оседают в чате поддержки.
- Повторы доставки всего несколько минут или нет журнала доставок.
- Незадокументированные лимиты и форматы ошибок.
- Непрозрачная стоимость одной транзакции — сравните с нашим разбором комиссий криптовалютных платёжных шлюзов.
Как получить доступ к API mistKET
Мерчантов подключает команда mistKET: напишите @mistnetwork в Telegram и укажите сайт, тип бизнеса и ожидаемый объём. После одобрения вы создадите API-ключ, секрет и настройки вебхуков в панели мерчанта. Типичная интеграция занимает полдня.
Перед началом изучите раздел для разработчиков, тарифы и полный справочник API.
