Appeal with Receipt

Submits a payment receipt for review. For a cancelled payment (CANCELLED / CANCELLED_APPEAL) an appeal is opened and the payment moves to DISPUTE. For a payment in any other status the receipt is only passed on for checking; the status does not change.

The outcome arrives via webhook and in the payment status. If a payment video is needed and your Telegram chat with the bot is connected, the request arrives there — reply to it with the video or send it with the request below. Without a chat, support will request the video.

Request

POST /v1/payments/{id}/appeal — multipart/form-data; headers: see Authorization.

Field	Type	Required	Description
receipt	file	yes	Receipt: up to 10 MB, png/jpg/jpeg/webp/heic/pdf
reason	string	no	Reason, up to 500 characters (e.g. "Payment was made")
amount	number	no	Actual amount if it differs from the order

Request example

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4-a716-446655440000/appeal \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -F "[email protected]" \
  -F "reason=Payment was made"

Response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ext_id": "order_12345",
  "status": "dispute",
  "dispute_opened": true,
  "delivered_to": 1,
  "receipt_url": "/uploads/receipts/550e8400-..._1790000000000.pdf"
}

Field	Type	Description
status	string	Payment status after the request
dispute_opened	boolean	true — the appeal was opened by this request
delivered_to	number	How many times the receipt was passed on for review (≥ 1)
receipt_url	string	Link to the stored receipt

Payment video

POST /v1/payments/{id}/appeal/video — multipart/form-data, field video: mp4/mov/webm/m4v, up to 19 MB. Available while the payment's appeal is open.

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4-a716-446655440000/appeal/video \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -F "[email protected]"

{ "id": "550e8400-e29b-41d4-a716-446655440000", "delivered_to": 1 }

Statuses

CANCELLED → DISPUTE → COMPLETED_APPEAL (approved) or CANCELLED_APPEAL (rejected).

Errors

Code	HTTP	Reason
PAY_002	400	Invalid parameters or not multipart/form-data
PAY_006	404	Payment not found
PAY_009	400	File is too large
PAY_010	400	Unsupported file type
APL_001	503	Appeals are temporarily unavailable — use open dispute
APL_002	409	An appeal for this payment is already under review
APL_004	502	Delivery failed, retry later
APL_005	400	File not attached (receipt / video)
APL_006	400	Reason longer than 500 characters
APL_007	404	No open appeal to attach the video to
SYS_001	500	Internal error