Диспуты

Открывайте диспуты для разрешения спорных ситуаций с платежами.

• Платёж отмечен как success, но получатель не получил средства
• Платёж отмечен как failed, но средства были списаны
• Некорректная сумма платежа
• Другие спорные ситуации

Диспут можно открыть только для ордеров со статусом:

• success
• failed

Нельзя открыть диспут для:

• created и in_progress — дождитесь завершения
• disputed — диспут уже открыт

В этих случаях придёт 400 DISPUTE_NOT_ALLOWED.

Нужно право orders.write.

curl -X POST 'https://b2b.lumowallet.io/orders/{orderId}/disputes' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Платёж отображается как успешный, но магазин не получил оплату"
  }'

Ответ:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "orderId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "submitted",
  "resolution": null,
  "reason": "Платёж отображается как успешный, но магазин не получил оплату",
  "adminComment": null,
  "resolvedBy": null,
  "refundAmount": null,
  "resolvedAt": null,
  "createdAt": "2026-03-10T12:00:00Z",
  "updatedAt": "2026-03-10T12:00:00Z"
}

Ответ — 201. После создания диспута:

• Ордер переходит в статус disputed. На этот переход может прийти вебхук order.status_changed — обрабатывайте его как обычно
• Диспут отправляется на рассмотрение

По ордеру в статусе success платёжная сторона в ответ на ваш запрос иногда сама открывает спор — тогда в ответе вернётся он, и в reason будет служебный текст dispute_created:… вместо вашего.

Диспут может открыться и без вашего запроса — например, если исполнитель не подтвердил оплату вовремя. Тогда ордер переходит в disputed, вы получаете вебхук order.status_changed, а в списке диспутов появляется диспут с причиной от платёжной стороны. Дальше он рассматривается так же, как ваш.

:::warning Исход диспута — в resolution, а не в status

status отвечает только на вопрос «рассмотрен или ещё нет». И выигранный, и проигранный диспут одинаково получают status: resolved. Чтобы понять исход, смотрите resolution.

:::

То есть resolution: confirm — это отказ по диспуту, несмотря на status: resolved.

:::note

Промежуточного статуса на практике не бывает: диспут переходит из submitted сразу в resolved. Значения in_review и rejected существуют в перечислении, но не выставляются — не стройте на них логику. Отказ по диспуту выражается как status: resolved + resolution: confirm.

:::

refundAmount заполняется при refund (полная сумма ордера) и при partial_refund (та часть, которую вернули). При confirm — всегда null.

:::warning refundAmount — это не «зачислено на баланс»

refundAmount показывает, какая часть ордера отменена, а не сколько денег пришло на баланс. Если к моменту решения средства ещё не были списаны (ордер держался в заморозке), возврат — это снятие заморозки: refundAmount заполнен, но баланс не растёт, освобождается замороженная сумма.

Реальное движение средств смотрите в истории баланса по referenceId = orderId. Решение администратора:

Закрытие по финальному статусу от платёжной стороны:

:::

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

curl -X GET 'https://b2b.lumowallet.io/disputes' \
  -H 'X-API-Key: YOUR_API_KEY'

Ответ содержит и сам диспут, и ордер, к которому он относится — отдельный запрос за ордером не нужен. Суммы в этом ответе приходят строками:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "resolved",
    "resolution": "refund",
    "reason": "Магазин не получил оплату",
    "adminComment": "Подтверждено: платёж не дошёл до получателя",
    "resolvedBy": "[email protected]",
    "refundAmount": "52.63000000",
    "resolvedAt": "2026-03-10T14:00:00Z",
    "createdAt": "2026-03-10T12:00:00Z",
    "updatedAt": "2026-03-10T14:00:00Z",
    "order": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "externalOrderId": "ORD-2026-8891",
      "status": "failed",
      "amountUsdt": "52.63000000",
      "amountRub": "5000.00",
      "rate": "95.01000000",
      "nspkBrandName": "Пятёрочка",
      "createdAt": "2026-03-10T11:40:00Z"
    }
  }
]

order.externalOrderId — ваш идентификатор, переданный при создании ордера; по нему удобно сводить диспуты со своей системой.

В order могут присутствовать и другие поля — они служебные и не входят в контракт, полагайтесь только на перечисленные выше.

# по вашему номеру заказа — достаточно части
curl 'https://b2b.lumowallet.io/disputes?search=387057' -H 'X-API-Key: ...'

# только возвраты
curl 'https://b2b.lumowallet.io/disputes?resolution=refund' -H 'X-API-Key: ...'

Без limit эндпоинт возвращает всю историю диспутов одним массивом — как и раньше. Общее число совпадений приходит в заголовке X-Total-Count. Нужно право orders.read.

Пока по ордеру открыт диспут, ордер находится в статусе disputed, и повторный запрос вернёт 400 DISPUTE_NOT_ALLOWED — второй диспут не создаётся. Если ответ на первый запрос потерялся, найдите диспут через GET /disputes?search={orderId}.

1. submitted — диспут создан
2. resolved — решение принято, исход в resolution

Время рассмотрения: обычно 1-3 рабочих дня.

Часть диспутов закрывается автоматически, без участия администратора: если по ордеру приходит финальный статус от платёжной стороны, диспут закрывается согласованно с ним (resolvedBy: wallet_callback).

Если платёжная сторона решает спор частичным возвратом, на баланс приходит операция order_partial_refund, а ордер при этом может остаться в статусе disputed, и диспут — в submitted. Сверяйтесь с историей баланса.

1. Описывайте подробно — чем больше деталей в reason, тем быстрее решение
2. Прикладывайте доказательства — скриншоты, логи (через поддержку)
3. Не дублируйте — один диспут на ордер
4. Отслеживайте статус — проверяйте список диспутов

Для ускорения рассмотрения свяжитесь с поддержкой:

• Telegram: @lumo_support_bot
• Укажите ID диспута и детали ситуации