Интеграция по API

Отправляйте выплаты с аккаунта Volet.com пользователям Volet.com и на внешние криптокошельки через Merchant API.

Mass Payout API позволяет приложению программно создавать, проверять и отслеживать транзакции выплат.

API поддерживает три основных сценария выплат:

• Выплаты пользователям Volet.com — перевод средств с вашего аккаунта Volet.com на другой аккаунт Volet.com.
• Криптовыплаты без конвертации — отправка криптовалюты с баланса той же криптовалюты на внешний криптокошелёк.
• Криптовыплаты с конвертацией — отправка криптовалюты на внешний криптокошелёк с другого поддерживаемого баланса, например USD, EUR, USDT или другой криптовалюты.

Как работают массовые выплаты через API

Merchant API создаёт одну транзакцию выплаты на один запрос.

Для пакета массовых выплат ваш бэкенд готовит список получателей и создаёт отдельную транзакцию выплаты для каждого элемента пакета.

Типичный порядок обработки пакета:

1. Подготовьте пакет выплат в своей системе.
2. Проверьте доступные балансы кошельков Volet.com.
3. При необходимости проверьте лимиты, тарифы и курсы обмена.
4. Проверьте каждую выплату перед созданием.
5. Создайте транзакции выплат через API.
6. Сохраните полученные ID транзакций в своей системе.
7. Отслеживайте статусы выплат через API.
8. Сверьте завершённые, неудачные, отменённые и возвращённые выплаты.

Перед началом

Для отправки массовых выплат через API нужны:

• Верифицированный аккаунт Volet.com.
• Настроенный API в разделе Платёжные инструменты.
• Достаточный баланс на аккаунте Volet.com.
• Данные получателей, нужные для каждого способа выплаты.

Как создать и настроить API, описано в разделе Подключение массовых выплат.

Аутентификация

Запросы к Merchant API требуют заголовков аутентификации.

Передавайте в каждом запросе к API следующие заголовки:

Заголовок	Описание
Api-Name	Название API, заданное в аккаунте Volet.com.
Account-Email	Email аккаунта Volet.com, которому принадлежит API.
Authentication-Token	Токен аутентификации запроса, сгенерированный с помощью секрета API.

Храните секрет API в тайне. Никогда не размещайте учётные данные API и токены аутентификации во фронтенд-коде, мобильных приложениях, ботах или клиентских скриптах.

Рекомендуемый порядок выплат

Перед созданием выплат бэкенд должен проверить и подготовить каждый элемент выплаты.

Рекомендуемый порядок:

1. Получите балансы кошельков.
2. Проверьте минимальные лимиты для выбранного способа выплаты и валюты.
3. Проверьте тарифы или комиссии.
4. Если выплата с конвертацией, проверьте информацию о курсе обмена.
5. Проверьте запрос на выплату.
6. Создайте транзакцию выплаты.
7. Сохраните полученный transactionId.
8. Периодически запрашивайте статус транзакции, пока выплата не достигнет итогового состояния.

Шаг 1. Получите балансы кошельков

Этим методом проверяйте доступные балансы кошельков Volet.com перед созданием выплат.

Эндпоинт:

GET /api/account/balances

Пример ответа:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Используйте walletId как кошелёк-источник при создании запросов на выплату.

Шаг 2. Проверьте лимиты и тарифы

Перед отправкой выплат проверьте минимальные лимиты и тарифы для выбранного способа выплаты и валютной пары.

Минимальные лимиты:

GET /api/account/limits/min

Тарифы:

GET /api/account/tariffs

Эти методы помогают избежать ошибок при создании выплат из-за неподдерживаемых сумм, валют или платёжных методов.

Шаг 3. Проверьте информацию о курсе обмена

Используйте информацию о курсе обмена, если выплата требует конвертации.

Эндпоинт:

POST /api/exchange-rate/information

Вызывайте его перед созданием выплат, у которых валюта источника и валюта выплаты различаются.

Примеры сценариев:

• Отправить USDT на внешний криптокошелёк с баланса в USD.
• Отправить BTC на внешний криптокошелёк с баланса в EUR.
• Конвертировать один поддерживаемый криптобаланс в другую валюту выплаты.

Способ выплаты 1. Выплаты пользователям Volet.com

Используйте этот способ, если у получателя есть аккаунт Volet.com.

Средства переводятся внутри Volet.com с вашего аккаунта на аккаунт Volet.com получателя.

Этот способ не требует подтверждений в блокчейне и не использует адреса внешних криптокошельков.

Проверка выплаты пользователю Volet.com

Проверьте выплату перед созданием транзакции.

Эндпоинт:

POST /api/withdrawal/validation/internal-other

Пример запроса:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Проверка проверяет данные выплаты, не создавая транзакцию.

Создание выплаты пользователю Volet.com

После успешной проверки создайте транзакцию выплаты.

Эндпоинт:

POST /api/withdrawal/internal-other

Пример запроса:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Пример ответа:

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Сохраните полученный transactionId в своей системе и отслеживайте по нему статус выплаты.

Дополнительно: проверка аккаунтов получателей в Volet.com

Если ваш сценарий выплат собирает email получателей до создания выплаты, можно проверить, существуют ли аккаунты Volet.com, ещё до создания запросов на выплату.

Эндпоинт:

GET /api/account/exists

Если сценарию нужны дополнительные проверки получателей, можно также сверить данные владельца аккаунта.

Эндпоинт:

GET /api/account/matching

Эти методы помогают сократить число неудачных выплат из-за неверных данных получателей.

Способ выплаты 2. Криптовыплаты без конвертации

Используйте этот способ, если хотите отправить криптовалюту с баланса той же криптовалюты на внешний криптокошелёк.

Например:

• Отправить USDT с баланса USDT на внешний адрес USDT TRC-20.
• Отправить BTC с баланса BTC на внешний адрес BTC.
• Отправить ETH с баланса ETH на внешний адрес ETH.

Получателю не нужен аккаунт Volet.com.

Проверка криптовыплаты без конвертации

Проверьте криптовыплату перед созданием транзакции.

Эндпоинт:

POST /api/withdrawal/validation/cryptowallet

Пример запроса:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Указывайте правильный destCurrency для токена и блокчейн-сети выплаты.

Для сетей, где нужен memo, destination tag или похожий идентификатор, передавайте его в поле address.memo.

Пример:

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Создание криптовыплаты без конвертации

После успешной проверки создайте транзакцию выплаты.

Эндпоинт:

POST /api/withdrawal/cryptowallet

Пример запроса:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Пример ответа:

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Способ выплаты 3. Криптовыплаты с конвертацией

Используйте этот способ, если валюта баланса-источника и валюта выплаты различаются.

Например:

• Отправить USDT на внешний кошелёк с баланса в USD.
• Отправить BTC на внешний кошелёк с баланса в EUR.
• Отправить USDC в одной поддерживаемой сети с другого поддерживаемого баланса.

Получатель получает криптовалюту на внешний криптокошелёк. Конвертация выполняется в ходе выплаты.

Проверка криптовыплаты с конвертацией

Проверьте выплату перед созданием транзакции.

Эндпоинт:

POST /api/withdrawal/validation/crypto-external

Пример запроса:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

В srcCurrency укажите валюту баланса-источника, а в destCurrency — криптовалюту и сеть, в которых получатель получит средства.

Создание криптовыплаты с конвертацией

После успешной проверки создайте транзакцию выплаты.

Эндпоинт:

POST /api/withdrawal/crypto-external

Пример запроса:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Пример ответа:

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

Поля запроса

Общие поля запроса на выплату:

Поле	Обязательное	Где используется	Описание
srcWalletId	Нет	Все способы выплат	ID кошелька-источника в вашем аккаунте Volet.com.
amount	Да	Все способы выплат	Сумма выплаты. Как она интерпретируется, зависит от action.
action	Да	Все способы выплат	Режим суммы. Возможные значения: GIVE, GET.
note	Нет	Все способы выплат	Внутреннее примечание или описание выплаты.
srcCurrency	Нет	Выплаты пользователям Volet.com, криптовыплаты с конвертацией	Валюта источника выплаты.
destCurrency	Да	Все способы выплат	Валюта, которая зачисляется получателю или отправляется на внешний криптокошелёк.
destEmail	Нет	Выплаты пользователям Volet.com	Email аккаунта Volet.com получателя.
destWalletId	Нет	Выплаты пользователям Volet.com	ID кошелька получателя, где применимо.
address.address	Да	Выплаты на внешние криптокошельки	Адрес криптокошелька получателя.
address.memo	Нет	Выплаты на внешние криптокошельки	Memo, destination tag или похожий идентификатор, если его требует выбранная сеть.
receiverInfo	Нет	Выплаты на внешние криптокошельки	Данные получателя: имя, email, дата рождения или название компании, где они нужны.

GIVE и GET

Поле action определяет, как интерпретируется сумма выплаты.

Действие	Значение
GIVE	Сумма считается суммой к отправке со стороны источника.
GET	Сумма считается суммой, которую должен получить получатель, где это поддерживается.

Для выплат с конвертацией валют проверяйте информацию о курсе обмена перед созданием выплаты. Так система сможет показать или сохранить ожидаемые суммы источника и получателя ещё до создания транзакции.

Отслеживание статуса выплаты

После создания выплаты сохраните полученный transactionId.

Актуальный статус выплаты получайте через поиск транзакции.

Эндпоинт:

GET /api/transactions/{id}

Можно также искать по истории транзакций.

Эндпоинт:

GET /api/transactions

Полезные фильтры:

Фильтр	Описание
paymentDirections	Фильтр по DEPOSIT или WITHDRAWAL.
transactionStatus	Фильтр по статусу транзакции.
wallets	Фильтр по ID кошельков.
startDate / endDate	Фильтр по диапазону дат создания.
searchLabel	Поиск по текстовой метке, где применимо.
offset / limit	Постраничный вывод результатов.
sortOrder	Сортировка результатов по дате создания.

Статусы транзакций

По статусу транзакции обновляйте статус выплаты в своей системе.

Статус	Значение	Что делать
CREATED	Транзакция выплаты создана.	Сохраните транзакцию и продолжайте отслеживать.
READY_TO_PROCESS	Выплата готова к обработке.	Продолжайте отслеживать.
PENDING	Выплата ожидает обработки.	Продолжайте отслеживать.
PROCESSING	Выплата обрабатывается.	Продолжайте отслеживать.
EXCHANGING	Идёт конвертация валюты.	Продолжайте отслеживать.
COMPLETED	Выплата завершена.	Отметьте выплату как завершённую в своей системе.
CANCELLING	Идёт отмена.	Дождитесь итогового статуса.
CANCELED	Выплата отменена.	Отметьте выплату как отменённую.
REFUNDING	Идёт возврат.	Дождитесь итогового статуса.
REFUNDED	Выплата возвращена.	Отметьте выплату как возвращённую.

Считайте выплату завершённой, только когда статус стал COMPLETED.

Отмена выплат

Некоторые транзакции можно отменить, пока отмена ещё возможна.

Эндпоинт:

DELETE /api/transactions/{transactionId}

Возможность отмены зависит от способа выплаты, статуса транзакции и этапа обработки.

Не рассчитывайте на отмену криптовыплаты после того, как транзакция отправлена в блокчейн. Проверяйте все адреса получателей, валюты, сети и суммы до создания выплаты.

Рекомендации по пакетной обработке

При массовых выплатах жизненным циклом пакета должен управлять ваш бэкенд.

Рекомендуемый подход:

1. Присвойте пакету выплат внутренний ID.
2. Присвойте каждой выплате внутренний ID элемента.
3. Проверьте каждый элемент выплаты до создания транзакций.
4. Создавайте транзакции выплат только для проверенных элементов.
5. Сохраните соответствие между внутренним ID элемента и полученным transactionId.
6. Отслеживайте каждую транзакцию отдельно.
7. Повторяйте только неудачные или не созданные элементы.
8. Сверьте итоговые статусы, прежде чем отмечать пакет как завершённый.

Избегайте повторных выплат. Если приложение повторяет запрос после тайм-аута, сначала проверьте, не была ли уже создана транзакция для этого элемента выплаты.

Обработка ошибок

При ошибках Merchant API возвращает структурированные ответы с ошибкой.

Частые случаи:

HTTP-статус	Значение
400	Запрос сформирован неверно или содержит недопустимые параметры.
401	Заголовки аутентификации отсутствуют или недействительны.
403	У API нет прав на запрошенную операцию.
404	Запрошенный ресурс не найден.
500	Непредвиденная ошибка сервера.

Когда возникает ошибка:

• Записывайте errorId в лог для поддержки и диагностики.
• Смотрите errorField, чтобы понять, к какому полю запроса относится ошибка.
• Не создавайте автоматически замещающую выплату, пока не убедитесь, что транзакция не была создана.
• Повторяйте запрос, только если это безопасно.

Чек-лист тестирования

Прежде чем отправлять реальные массовые выплаты, проверьте весь сценарий.

Для выплат пользователям Volet.com:

• Проверку аккаунта получателя.
• Проверку выплаты.
• Создание выплаты.
• Отслеживание статуса транзакции.
• Сценарии завершения, отмены и ошибки.

Для криптовыплат без конвертации:

• Правильный выбор токена и сети.
• Обработку адреса и memo.
• Проверку выплаты.
• Создание выплаты.
• Отслеживание транзакции в блокчейне.
• Обработку неверного адреса или неподдерживаемой сети.

Для криптовыплат с конвертацией:

• Проверку баланса.
• Проверку курса обмена.
• Проверку выплаты.
• Создание выплаты.
• Статусы EXCHANGING и COMPLETED.
• Сверку сумм в валюте источника и валюте получателя.

Для пакетной обработки:

• Обработку частичного сбоя пакета.
• Логику повторов.
• Защиту от дублей.
• Соответствие между пакетом и транзакциями во внутренней системе.
• Итоговый отчёт сверки.

Важно

• API создаёт одну транзакцию выплаты на один запрос.
• За организацию пакетов отвечает ваш бэкенд.
• Всегда проверяйте выплаты перед созданием транзакций.
• Всегда сохраняйте полученные значения transactionId.
• Для отслеживания итогового статуса используйте поиск транзакции или историю транзакций.
• Не отмечайте выплату как завершённую, пока статус не станет COMPLETED.
• Для криптовыплат всегда проверяйте адрес получателя, токен, сеть и memo перед созданием транзакции.
• Отправка криптовалюты на неверный адрес или в неверной сети может привести к безвозвратной потере средств.
• Учётные данные API никогда не должны попадать во фронтенд-код.

См. также

• Подключение массовых выплат — настройка API перед отправкой выплат
• Выплаты пользователям Volet.com — внутренние выплаты на аккаунты Volet.com
• Кастодиальные криптовыплаты — отправка криптовалюты на внешние кошельки с аккаунта Volet.com
• Обзор массовых выплат — сравнение способов и моделей выплат
• Справочник API — полное описание методов, параметров и ответов