Кратко
Для массовых выплат через API нужна очередь с ограниченным числом одновременных запросов. Каждый POST /v1/withdrawals создает выплату одному получателю. Сохраните external_order_id вместе с заявкой до первой отправки и используйте тот же идентификатор и данные при повторных запросах. Стандартный лимит 30 запросов в секунду общий для аккаунта и не означает скорость завершения переводов. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production. Комиссия Paymos за вывод — 0 %, сетевая комиссия субсидируется.
Массовые автоматические выплаты в криптовалюте — критически важная часть инфраструктуры современного финтеха. Партнерские сети (CPA), выплачивающие вознаграждения тысячам вебмастеров, гемблинг-платформы с моментальным выводом выигрышей, Web3-протоколы и международные IT-компании с распределенной зарплатной сеткой ежедневно генерируют тысячи исходящих транзакций.
Однако масштабирование криптовалютных выплат кардинально отличается от работы с банковскими шлюзами. Если в банковской системе реестр выплат отправляется одним файлом, то в блокчейне действуют правила строгого распределенного консенсуса, последовательные номера nonce, аукционы газа в мемпуле и полная необратимость транзакций. Любая неотработанная ошибка может привести к повторному списанию средств или полной парализации очереди выплат.
Для построения надежного конвейера массовых выплат требуется специализированная распределенная архитектура.
Почему последовательные выплаты зависают под нагрузкой: проблема Nonce
Типичная ошибка начинающих разработчиков — реализация выплат простым синхронным циклом: бэкенд выбирает 300 заявок из базы данных и по очереди дергает метод отправки транзакции. В боевых условиях такая схема ломается из-за порядкового номера nonce.
В сетях на базе Ethereum (EVM) транзакции одного отправителя выполняются в порядке nonce: $0, 1, 2, \dots$ Если одна из них остается в ожидании, следующие переводы с того же адреса могут ждать за ней. Частота запросов API и число завершенных переводов в блокчейне — разные показатели.
Попытки хаотично поднимать nonce в параллельных потоках приводят к коллизиям и ошибкам узла nonce too low или replacement transaction underpriced. Для стабильной работы под нагрузкой требуется разделение потоков.
Архитектура 1: Паттерн Transactional Outbox для финансовой надежности
Шаблон Transactional Outbox позволяет записать заявку на выплату и изменение внутреннего баланса одной транзакцией базы данных. Вместе с заявкой сохраните external_order_id, чтобы после сбоя воркер повторил исходный запрос с тем же идентификатором.
Принципы надежного конвейера:
- Атомарность списания: Списание баланса пользователя в приложении и создание задачи на выплату выполняются в одной транзакции базы данных.
- Ключи идемпотентности (Idempotency Keys): Сохраните уникальный
external_order_idдо первой отправки и повторяйте запрос с тем же идентификатором и данными. Новый идентификатор нужен только для новой выплаты. Подробнее о защите от дублей читайте в статье об идемпотентности платежных вебхуков. - Асинхронные воркеры: Воркеры выбирают заявки из очереди, например через
FOR UPDATE SKIP LOCKED. Ограничьте общее число одновременных запросов и увеличивайте паузу между попытками при ошибках. При HTTP429учитывайте заголовокRetry-After.
Архитектура 2: Устранение коллизий Nonce через несколько кошельков-отправителей
В собственном сервисе выплат несколько кошельков позволяют разделить последовательности nonce. Это вариант архитектуры, который сам по себе не задает скорость завершения переводов:
$$\text{Кластер хранилищ} = {V_1, V_2, V_3, \dots, V_m}$$
При такой схеме нужно учитывать состояние каждого отправителя:
- Отдельно отслеживать последовательность nonce и ожидающие транзакции каждого кошелька.
- Распределять новые заявки с учетом ожидающих транзакций; дополнительные кошельки не завершают уже задержанный перевод.
- Проверять баланс и необходимые сетевые ресурсы до отправки.
О принципах безопасной изоляции приватных ключей читайте в материале о безопасности горячих кошельков.
Архитектура 3: Мультичейн-выплаты в сетях TRON, EVM и TON
Платформам часто приходится платить получателям в нескольких сетях: получатели держат средства в разных сетях и на разных биржах.
API выплат сводит различия между сетями к единой схеме:
- TRON (USDT TRC-20): Поддерживает выплаты USDT. Энергия влияет на стоимость перевода; подробнее — в материале об аренде энергии TRON.
- EVM-сети (Arbitrum, BSC, Polygon): Поддерживают выплаты USDT и USDC. Base поддерживает только USDC; выбирайте доступное направление для своего актива.
- TON (USDT): Поддерживает выплаты USDT. Срок перевода зависит от текущих условий сети.
Шлюз нормализует ответы разных сетей в единый формат вебхуков, избавляя мерчанта от поддержки специфичных протокольных клиентов. Всего для выплат доступно 11 сетей (сети NEAR и Sui работают только на прием депозитов).
Предварительный AML-скрининг получателей
Серьезный риск автоматических выплат — случайно перевести средства санкционному лицу, даркнет-маркетплейсу или на адрес с украденными активами. Если горячий кошелек отправит стейблкоины на адрес из санкционного списка OFAC, бизнесу грозят серьезные регуляторные последствия.
- Оценка риска адреса: перед маршрутизацией выплаты адрес получателя проверяется по источникам TRM Labs, Binance AML, AMLBot, PureFi и базе провайдера проверки.
- Остановка рискованной выплаты: если адрес не проходит проверку, выплата не отправляется. Она переходит в статус
failed(вебхукwithdrawal.failed), а вся зарезервированная суммаamount + feeвозвращается на доступный баланс мерчанта.
Проверка может задержать или остановить выплату: принятый запрос API не гарантирует немедленной отправки в сеть.
Сетевые комиссии: субсидии на выплаты и энергия TRON
При расчете расходов учитывайте комиссию сервиса и сетевые ресурсы:
- 0% комиссии Paymos за вывод и субсидированная комиссия сети: Paymos берет 0% комиссии за вывод. Мерчант платит только указанную комиссию сети для выбранного направления, причем каждое направление выплат субсидируется: мерчант платит меньше, чем списывает блокчейн. Если выплата не состоялась или отменена, вся зарезервированная сумма и комиссия возвращаются на доступный баланс.
- Энергия TRON и указанная комиссия: Энергия и другие ресурсы сети влияют на стоимость перевода в TRON. Ориентируйтесь на указанную комиссию выбранного направления, а не на фиксированную цену в долларах. Информация о комиссиях доступна на странице цен Paymos.
Интеграция через REST API Paymos
Через Host-to-Host REST API Paymos вы создаете отдельные выплаты из своей очереди и отслеживаете их статус.
1. Отправка выплаты через API
Бэкенд отправляет отдельный POST /v1/withdrawals для каждого получателя. Используйте ключ Payout (rk_) и подпись HMAC-SHA256. Значения заголовков ниже — шаблоны: вычисляйте подпись для точных байтов запроса и текущего времени Unix. По умолчанию адрес получателя должен быть в белом списке выводов.
POST /v1/withdrawals HTTP/1.1
Host: api.paymos.io
Authorization: HMAC-SHA256 rk_live_<key_id>:<base64_signature>
X-Request-Timestamp: <current_unix_seconds>
Content-Type: application/json
{
"currency": "USDT",
"network": "TRC20",
"amount": "25.00",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"external_order_id": "payout_usr_101"
}
Новая выплата возвращается с HTTP 201 Created и статусом created. Повторный запрос с тем же external_order_id возвращает HTTP 200 OK и существующую выплату. Сумма и комиссия в примере условные и не являются тарифом:
{
"withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
"external_order_id": "payout_usr_101",
"status": "created",
"is_final": false,
"is_test": false,
"amount": "25.00",
"fee": "0.50",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"created_at": 1739277600
}
Стандартный лимит 30 запросов в секунду общий для API-запросов аккаунта. Ограничьте число одновременных запросов, делайте паузы при повторных попытках и учитывайте Retry-After при HTTP 429. Этот лимит не задает скорость завершения переводов. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production.
2. Получение вебхука об исполнении
При завершении выплаты Paymos отправляет withdrawal.completed в конверте вебхука с версией формата. В data лежит снимок выплаты: status, is_final и хеш завершенной транзакции:
{
"event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
"event_type": "withdrawal.completed",
"version": 1,
"occurred_at": 1739281200,
"data": {
"withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
"external_order_id": "payout_usr_101",
"status": "completed",
"is_final": true,
"is_test": false,
"amount": "25.00",
"fee": "0.50",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
"explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
"created_at": 1739277600,
"completed_at": 1739281200
}
}
Неуспешная выплата вызывает withdrawal.failed, отмена — withdrawal.cancelled. В обоих случаях вся зарезервированная сумма и комиссия возвращаются на доступный баланс. Проверяйте подпись по исходному телу вебхука и отсекайте повторы по event_id. Изменения в учете связывайте с data.withdrawal_id; события могут приходить не по порядку. При withdrawal.completion_rewound завершенная выплата возвращается в signed и требует дальнейшего отслеживания.
Подробнее о механике финализации транзакций читайте в руководстве по скорости вывода криптовалюты и решениях для SaaS-бизнеса.
| Архитектурный подход | Отправка запросов | Управление nonce | Затраты на комиссии сети | Оптимально для |
|---|---|---|---|---|
| 1. Синхронный цикл RPC | Зависит от сети и реализации | Контролируется вашей интеграцией | Зависит от сети и ее ресурсов | Небольшие пет-проекты, внутренние тесты |
| 2. Запуск выплат в дашборде | До 50 получателей в одном активе и одной сети; только Production | Nonce отправителя контролирует Paymos | Субсидированный тариф сети | Регулярные зарплаты, ручные выплаты аффилиатам |
| 3. Автоматический воркер API (POST /v1/withdrawals) | Один получатель на запрос; общий лимит аккаунта 30 запросов/с | Nonce отправителя контролирует Paymos | Субсидированный тариф (0% комиссии Paymos) | iGaming, биржи, проп-трейдинг, агрегаторы |
Частые вопросы
Почему нельзя отправлять выплаты простым циклом со скрипта?
В сетях EVM транзакции одного отправителя выполняются в порядке nonce. Если транзакция #5 остается в ожидании, следующие переводы с того же адреса могут ждать за ней. Это не означает, что все запросы API попадают в одну очередь блокчейна.
Как защититься от повторной отправки выплат при сбое сети?
Сохраните external_order_id с заявкой до первого запроса. После тайм-аута повторите запрос с тем же идентификатором и теми же данными. Paymos вернет существующую выплату. Transactional Outbox позволяет записать заявку и изменение внутреннего баланса одной транзакцией базы данных.
Как снижаются комиссии при массовых выплатах?
Комиссия Paymos за вывод — 0 %, сетевая комиссия субсидируется. Объединение заявок в очередь само по себе не снижает комиссию. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production.
Что происходит, если адрес получателя заблокирован по AML?
Перед маршрутизацией выплаты Paymos проверяет адрес получателя по данным TRM Labs, Binance AML, AMLBot, PureFi и базе провайдера проверки. Если адрес не проходит проверку, выплата не отправляется и получает статус failed. Вся зарезервированная сумма вместе с сетевой комиссией возвращается на доступный баланс мерчанта.
Какие блокчейн-сети поддерживаются для выплат?
Для выплат доступны 11 основных сетей с учетом актива и доступности направления. TRON и TON поддерживают USDT; Arbitrum, BSC и Polygon — USDT и USDC. Base поддерживает только USDC. NEAR и Sui работают только на прием депозитов. Срок перевода зависит от сети и ее текущей нагрузки.
Когда НЕ стоит использовать API массовых выплат в криптовалюте
- Если ручных выплат в дашборде достаточно и интеграция с API не нужна.
- Если вы выплачиваете редкие невзаимозаменяемые токены (NFT) или неликвидные альткоины, требующие индивидуальной эскроу-проверки.
- Если в вашей архитектуре нет возможности развернуть Transactional Outbox с гарантией идемпотентности.
- Если по правилам комплаенса каждый исходящий перевод, независимо от суммы, должны одобрить два сотрудника: в Paymos нет цепочки согласования несколькими людьми, поэтому постройте ее в своей учетной системе до вызова API.
Источники
Последняя проверка: 7 нояб. 2026 г.


