Open Dispute

Opens a dispute on a cancelled payment. Used when the client made the payment but it was cancelled by the system.

Endpoint

POST /v1/payments/{id}/dispute

Request Parameters

The request is accepted both as application/json and as multipart/form-data (when a receipt file is attached).

Parameter	Type	Required	Description
amount	number	No	Actual payment amount (if different)
receipt_url	string	No	URL of the receipt/screenshot on your side
comment	string	No	Comment

Receipt file — multipart/form-data

Field	Type	Description
data	string (JSON)	The parameters above as a single JSON string
receipt	file	Receipt file. The names attachment, file, proof are also accepted

File limits: up to 10 MB, formats png, jpg, jpeg, webp, heic, pdf. The uploaded receipt is visible to the person reviewing the dispute, so no public hosting of your own is required.

If the payment was executed by an external provider, the dispute is also opened on their side automatically — together with the attached receipt (the uploaded file, or one downloaded from receipt_url). No extra call is needed; a receipt sent later via receipt transfer for a payment in dispute status is forwarded to the provider as well.

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":"Client provided a payment receipt"}' \
  -F "[email protected]"

A receipt can also be sent later via POST /payments/{id}/receipt — reopening the dispute is not needed.

Request Example

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": "Client provided a payment receipt"
  }'

Response

{
  "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": "Client provided a payment receipt",
    "created_at": "2026-01-30T12:45:00Z"
  },
  "created_at": "2026-01-30T12:15:00Z"
}

Restrictions

• A dispute can be opened only for cancelled payments (status = CANCELLED or CANCELLED_APPEAL)
• Re-opening is possible after cancelling the dispute

Dispute Outcomes

Status	Description
DISPUTE	Dispute opened, under review
COMPLETED	Dispute approved, funds credited
CANCELLED	Dispute rejected

Cancelling a Dispute

To cancel an active dispute, use POST /payments/{id}/dispute/cancel.

Errors

Code	HTTP	Description
PAY_002	400	Invalid request parameters
PAY_006	404	Payment not found
DIS_001	400	A dispute can only be opened for CANCELLED / CANCELLED_APPEAL
DIS_002	409	Dispute already exists