Жизненный цикл выплаты

pending ──▶ waiting_trader ──▶ in_progress ──▶ success
   │                │                 │            │
   └────────────────┴────────┬────────┘            │ спор в вашу пользу
                             ▼                     │
                           fail ◀──────────────────┘
                             │
                             ▼
                  возврат средств на баланс

Редкие переходы: success → fail — спор решён в вашу пользу; fail → success — исполнение подтвердили после возврата, см. повторное списание.

Статус	Что значит
`pending`	Списано, заявка ещё не подтверждена сервисом выплат. Обычно живёт секунды; если сервис выплат не ответил, заявка остаётся в `pending`, пока сверка не передаст её повторно
`waiting_trader`	В очереди, ждём исполнителя. Отмена возможна только здесь
`in_progress`	Исполнитель взял заявку
`success`	Рубли отправлены получателю
`fail`	Не выполнена, средства возвращены на баланс. Причина — в `failReason`

Причины провала

`failReason`	Что случилось
`timeout`	Заявку не исполнили вовремя
`no_traders`	Не нашлось исполнителя
`bank_not_exists`	Банк получателя не найден
`requisites_invalid`	Реквизиты получателя неверны
`trader_declined`	Исполнитель отказался от заявки
`dispute_lost`	Спор решён в вашу пользу — заявка отменена, средства возвращены
`cancelled_by_admin`	Заявку отменила поддержка
`cancelled_by_merchant`	Вы отменили заявку сами
`service_unavailable`	Сервис выплат не принял заявку, списание откатили
`other`	Другая причина, подробности — в `comment`

Каждая смена статуса приезжает вебхуком payout.status_changed — см. Webhooks. Исключение — возврат в success после возврата средств: на него приходит payout.recharged. Параллельно статус всегда можно спросить сами:

curl 'https://b2b.lumowallet.io/payouts/{id}' -H 'X-API-Key: YOUR_API_KEY'

Возврат средств

Провал заявки возвращает списанное на баланс автоматически и ровно один раз. Признак — поле refundedAt: пока оно заполнено, деньги у вас. Ориентируйтесь на него, а не на сам факт fail.

Возвращается вся списанная сумма (chargedUsdt), в USDT, по курсу заявки. Курс за это время мог измениться — вас это не касается, вернётся ровно столько, сколько списали.

Отмена

POST /payouts/{id}/cancel

Возможна, только пока заявку не взял исполнитель, то есть в статусе waiting_trader. Заявка уходит в fail с failReason: cancelled_by_merchant, средства возвращаются сразу. Отмена и спор требуют право payouts.write.

Если исполнитель уже взял заявку, придёт PAYOUT_NOT_CANCELABLE — дальше только спор.

Споры

POST /payouts/{id}/dispute
Content-Type: multipart/form-data

Спор — про «деньги не дошли». Разбирательство ведёт сервис выплат: он хранит вложения, опрашивает исполнителя и выносит вердикт, а мы передаём обращение и показываем состояние.

Поле	Описание
`comment`	Суть претензии, обязательно
`files`	До 3 файлов, каждый не больше 5 МБ

curl -X POST 'https://b2b.lumowallet.io/payouts/{id}/dispute' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'comment=Получатель не видит зачисление, прошло 40 минут' \
  -F '[email protected]'

Состояние спора приезжает в карточке заявки:

"dispute": {
  "id": "025127ce-5a76-46e8-89ef-8ccf422248fb",
  "status": "open",
  "resolution": null,
  "comment": null,
  "openedAt": "2026-08-26T11:34:11.596Z",
  "resolvedAt": null
}

comment — комментарий поддержки сервиса выплат к решению; пока спор открыт, он пустой. Ваш текст обращения в карточке не показывается.

Когда спор решают в вашу пользу, заявка приходит в fail с failReason: dispute_lost, а resolution становится user_won — средства возвращаются обычным путём. Решение в пользу исполнителя — resolution: trader_won — оставляет заявку в success.

Когда спор открыть нельзя (PAYOUT_DISPUTE_NOT_ALLOWED):

заявку ещё никто не взял — её проще отменить и получить деньги сразу;
заявка уже провалилась — средства и так вернулись;
спор по этой заявке уже открыт.

Список выплат

GET /payouts?status=&search=&limit=&offset=

search ищет по вашему externalId (в том числе по части) или по нашему id — целиком либо по первым символам.

{ "payouts": [ /* … */ ], "total": 42 }

Редкий случай: повторное списание

Заявку может признать провалившейся, вернуть вам деньги, а потом подтвердить исполнение — например, если спор решили в пользу исполнителя после ложного таймаута. Тогда сумма списывается повторно, а вы получаете отдельное событие payout.recharged: из поля status (снова success) повторное списание не видно никак.