Создание выплаты

POST /payouts

Списывает USDT с баланса компании и передаёт заявку исполнителю.

Параметры

Параметр	Тип	Обяз.	Описание
`amountRub`	number	да	Сумма в рублях — ровно столько получит получатель
`requisiteType`	`card` \| `phone`	да	Куда платим
`requisite`	string	да	Номер карты (16–19 цифр) или телефона (10–15 цифр)
`bankId`	string	для `phone`	ID банка из `GET /payouts/banks`
`recipientFirstName`	string	нет	Имя получателя
`recipientLastName`	string	нет	Фамилия получателя
`externalId`	string	нет	Ваш идентификатор выплаты

Формат реквизита произвольный — разделители, скобки и пробелы мы вырежем сами.

Почему банк — это id, а не строка

Название банка уходит исполнителю, и он ищет его у себя. Произвольный текст вроде «банк карты» он не найдёт, и заявка вернётся отказом уже после списания. Поэтому банк принимается только идентификатором из справочника.

Для выплаты на карту банк не нужен: эмитент однозначно определяется номером, исполнитель видит его в своём приложении. Для перевода по телефону банк обязателен — к одному номеру привязано несколько банков, и без выбора непонятно, куда доставлять.

ФИО получателя

Необязательны — деньги идут по номеру, а не по имени. Смысл в сверке на стороне исполнителя: приложение банка покажет ему имя получателя, и разойтись оно может только если в реквизите опечатка. Это единственный шанс поймать ошибку до того, как деньги уйдут чужому человеку.

Idempotency-Key

Передавайте всегда. Ретрай с тем же ключом вернёт ту же заявку, а не выплатит второй раз. Уникальность ключа — в пределах вашей компании.

Без заголовка повторный запрос — это вторая выплата. Это не баг: не получив ключа, мы не можем отличить ретрай от намеренной второй отправки на тот же номер.

Пример

curl -X POST 'https://b2b.lumowallet.io/payouts' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 9f1c8d2e-4b7a-4c11-9f0e-2b8a1d5c3e77' \
  -H 'Content-Type: application/json' \
  -d '{
    "amountRub": 12000,
    "requisiteType": "phone",
    "requisite": "+79000000000",
    "bankId": "bank100000000111",
    "recipientFirstName": "Иван",
    "recipientLastName": "Иванов",
    "externalId": "payout-12345"
  }'

{
  "id": "0d6c0d28-02e3-4366-bab8-3347f7f4f799",
  "externalId": "payout-12345",
  "status": "waiting_trader",
  "amountRub": 12000,
  "chargedUsdt": 147.71,
  "rate": 81.24,
  "requisiteType": "phone",
  "requisite": "+79000000000",
  "bankId": "bank100000000111",
  "bank": "Сбербанк",
  "recipientFirstName": "Иван",
  "recipientLastName": "Иванов",
  "failReason": null,
  "comment": null,
  "refundedAt": null,
  "dispute": null,
  "takenAt": null,
  "completedAt": null,
  "createdAt": "2026-08-25T13:28:26.887Z"
}

chargedUsdt — сколько списано с баланса. bank — название на момент создания заявки: справочник могут переименовать, а в закрытой заявке должно остаться то, что видел исполнитель.

Предварительный расчёт

POST /payouts/quote

Считает сумму списания без создания заявки и без блокировки средств.

curl -X POST 'https://b2b.lumowallet.io/payouts/quote' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "amountRub": 12000 }'

{ "amountRub": 12000, "rate": 81.24, "amountUsdt": 147.71 }

Курс здесь и в созданной заявке может отличаться на движение рынка между запросами: фиксируется он в момент создания.

Справочник банков

GET /payouts/banks

Снимок списка участников СБП.

[
  {
    "id": "bank100000000111",
    "name": "Сбербанк",
    "logoUrl": "https://api.lumowallet.io/bank-logos/bank100000000111.webp",
    "popular": true
  }
]

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

Ошибки

`errorCode`	Что произошло
`PAYOUTS_NOT_ENABLED`	Выплаты не подключены вашей компании
`AMOUNT_BELOW_MIN` / `AMOUNT_ABOVE_MAX`	Сумма вне лимитов, границы в `details`
`PAYOUT_REQUISITE_INVALID`	Неверная длина номера карты или телефона
`PAYOUT_BANK_REQUIRED`	Перевод по телефону без `bankId`
`PAYOUT_BANK_UNKNOWN`	Банка нет в справочнике
`INSUFFICIENT_BALANCE`	Не хватает свободного баланса, доступное в `details`
`PAYOUT_ACTIVE_LIMIT`	Превышен лимит одновременных заявок
`PAYOUT_REQUISITE_COOLDOWN`	На этот реквизит недавно платили, `details.availableAt`
`PAYOUT_OUTSIDE_WORKING_HOURS`	Вне часов приёма
`PAYOUT_SERVICE_REJECTED`	Сервис выплат не принял заявку — средства уже вернулись
`PAYOUT_SERVICE_UNAVAILABLE`	Сервис не ответил — заявка принята, средства не возвращены

Последние две различайте внимательно. PAYOUT_SERVICE_REJECTED означает, что заявки не существует и деньги на балансе. PAYOUT_SERVICE_UNAVAILABLE означает неизвестность: заявка могла создаться, поэтому мы не возвращаем деньги вслепую — её судьба выяснится автоматически, а статус придёт вебхуком. Не повторяйте такой запрос с новым Idempotency-Key — так вы создадите вторую выплату. Повтор с тем же ключом безопасен и вернёт ту же заявку.