Диспуты

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

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

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

• success
• failed

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

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

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"
}

После создания диспута:

• Ордер переходит в статус disputed
• Диспут отправляется на рассмотрение

:::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.63,
    "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.63,
      "amountRub": 5000.00,
      "rate": 95.01,
      "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 эндпоинт возвращает всю историю диспутов одним массивом — как и раньше. Если limit передан, общее число совпадений приходит в заголовке X-Total-Count.

Если диспут уже открыт для ордера:

• API вернёт существующий диспут
• Новый диспут не создаётся
• Это позволяет безопасно повторять запрос

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

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

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

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

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

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