Споры

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

Когда открывать спор

Ситуация	Открывать спор
Клиент перевёл деньги, сделка ушла в canceled по тайм-ауту	Да
Клиент перевёл сумму, отличную от суммы сделки	Да
Клиент утверждает, что платил, но подтверждения нет	Да, если есть чек
Сделка в success, но клиент недоволен	Нет — обращайтесь к менеджеру
Клиент не платил и не собирался	Нет — сделка отменится сама

Спор можно открыть по сделке в статусе active или canceled. По сделке в любом другом статусе запрос вернёт TRADE_NOT_FOUND.

Заметка

Если сделка ещё active, спор не начнётся сразу — он встанет в очередь и откроется, когда окно оплаты закроется. Это позволяет подать спор заранее, не дожидаясь отмены по тайм-ауту.

Ограничения

Ограничение	Значение
Срок подачи	14 дней с момента создания сделки
Число споров по одной сделке	Ограничено настройкой кабинета — уточните лимит у менеджера
Размер файла чека	До 5 МБ
Форматы чека	pdf, png, jpg, jpeg, heic, heif, а также видео mp4, mov, 3gp, avi, mkv, webm, mpeg

После 14 дней запрос вернёт MERCHANT_DISPUTE_CREATE_WINDOW_EXPIRED, после исчерпания попыток — MERCHANT_MAX_APPEALS_PER_TRADE_REACHED. Оба ограничения не обходятся повторной отправкой.

Как открыть спор

Спор открывается в два запроса: сначала загружается чек, потом создаётся сам спор.

Шаг 1. Загрузите чек

POST /file/pay-in/invoice/upload?id={tradeId} HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: multipart/form-data
X-Secure-Key: <ваш API-ключ>

Файл передаётся в поле file. В ответ придёт ключ:

{ "uploadMetaKey": "mjuikrewfmnrgbhty4ui3okqwmefnbght4yu3irkefjghy4tu38i" }

Шаг 2. Создайте спор

POST /payment/pay-in/{id}/dispute HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: application/json
X-Secure-Key: <ваш API-ключ>

{
  "uploadMetaKey": "mjuikrewfmnrgbhty4ui3okqwmefnbght4yu3irkefjghy4tu38i",
  "amount": 4850.00
}

Поле	Обяз.	Описание
uploadMetaKey	да	Ключ, полученный на шаге 1
amount	нет	Фактически уплаченная сумма, если она отличается от суммы сделки. По умолчанию берётся сумма сделки

В пути {id} принимается как идентификатор сделки на нашей стороне, так и ваш merchantTransactionId. Сегмент перед {id} — тип сделки: pay-in или pay-out.

Осторожно

Указывайте в amount ровно ту сумму, которая указана в чеке. Именно она станет итоговой суммой сделки, если спор разрешится в вашу пользу, и по ней пройдёт зачисление на баланс.

Как отменить спор

Если спор открыт по ошибке или клиент нашёлся:

POST /payment/pay-in/{id}/dispute/cancel

Отмена возможна, пока решение не принято.

Чем заканчивается спор

Сделка выходит из dispute в один из финальных статусов:

Исход	Что произошло
success	Платёж подтверждён на исходную сумму, средства зачислены
success_changed	Платёж подтверждён, сумма пересчитана по факту. Итог — в поле amount уведомления
canceled	Платёж не подтверждён, зачисления не будет

Если спор отклонён, причина приходит в dispute.disputeTraderDeclineReason:

Значение	Что означает
payment_not_found	Платёж не найден в выписке по реквизиту
different_requisite	Платёж ушёл на другой реквизит
other_transaction	Чек относится к другой операции
other_bank	Платёж пришёл из другого банка, чем указано в сделке

Сколько ждать

Спор рассматривается человеком, поэтому он идёт дольше обычной сделки. Штатное окно на ответ противоположной стороны — 30 минут; в ночные часы по московскому времени оно продлевается до утра.

Пока спор идёт, сделка может несколько раз сменить статус. Финальным считайте только success, success_changed или canceled.

Опасно

Не запускайте бизнес-логику по спорной сделке до её закрытия. Отгрузка «по чеку от клиента» до решения по спору — прямой канал для мошенничества с поддельными квитанциями.

Что дальше

• Статусы сделок — переходы dispute → success / canceled
• Загрузить чек — полный контракт метода
• Коды ошибок — отказы при создании спора