Открытие апелляции

Открывает апелляцию по отменённому платежу. Используется когда клиент произвёл оплату, но платёж был отменён системой.

Endpoint

POST /v1/payments/{id}/dispute

Параметры запроса

Запрос принимается в двух форматах: application/json и multipart/form-data (если нужно приложить файл чека).

Параметр	Тип	Обязательный	Описание
amount	number	Нет	Фактическая сумма платежа (если отличается)
receipt_url	string	Нет	URL чека/скриншота на вашей стороне
comment	string	Нет	Комментарий

Файл чека — multipart/form-data

Поле	Тип	Описание
data	string (JSON)	Параметры выше одной JSON-строкой
receipt	file	Файл чека. Также принимаются имена attachment, file, proof

Ограничения файла: не больше 10 МБ, форматы png, jpg, jpeg, webp, heic, pdf. Загруженный чек виден разбирающему апелляцию — внешний хостинг для картинки не нужен.

Вместо JSON-части можно передать те же параметры отдельными полями формы (amount, comment, receipt_url).

Если платёж исполнял внешний провайдер, апелляция автоматически открывается и на его стороне — вместе с приложенным чеком (файл или скачанный по receipt_url). Отдельного запроса от вас для этого не нужно; чек, досланный позже через передачу чека по платежу в статусе dispute, тоже уходит провайдеру.

Пример запроса

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4/dispute \
  -H "Content-Type: application/json" \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: your-signature" \
  -d '{
    "receipt_url": "https://your-site.com/receipts/12345.jpg",
    "comment": "Клиент предоставил чек об оплате"
  }'

Пример: апелляция с файлом чека

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4/dispute \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: your-signature" \
  -F 'data={"amount":5000,"comment":"Клиент предоставил чек об оплате"}' \
  -F "[email protected]"

В ответе dispute.receipt_url будет ссылкой на наше хранилище (/uploads/receipts/...), а не на внешний адрес.

Ответ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ext_id": "order_12345",
  "amount": 5000,
  "currency": "RUB",
  "status": "dispute",
  "method": "SBP",
  "dispute": {
    "amount": null,
    "receipt_url": "https://your-site.com/receipts/12345.jpg",
    "comment": "Клиент предоставил чек об оплате",
    "created_at": "2026-01-30T12:45:00Z"
  },
  "created_at": "2026-01-30T12:15:00Z"
}

Ограничения

• Апелляцию можно открыть только для отменённых платежей (status = CANCELLED или CANCELLED_APPEAL)
• Повторное открытие возможно после отмены апелляции

Результаты апелляции

Статус	Описание
DISPUTE	Апелляция открыта, на рассмотрении
COMPLETED	Апелляция одобрена, средства зачислены
CANCELLED	Апелляция отклонена

Отмена апелляции

Для отмены активной апелляции используйте POST /payments/{id}/dispute/cancel.

Ошибки

Код	HTTP	Описание
PAY_002	400	Неверные параметры запроса
PAY_006	404	Платёж не найден
DIS_001	400	Апелляцию можно открыть только для CANCELLED / CANCELLED_APPEAL
DIS_002	409	Апелляция уже существует
PAY_009	400	Файл чека больше 10 МБ
PAY_010	400	Неподдерживаемый формат файла чека

Дозагрузка чека

Если чека в момент открытия апелляции ещё нет, его можно дослать отдельным запросом POST /payments/{id}/receipt — апелляцию для этого переоткрывать не нужно.