Sending a receipt

Attaches a payment receipt — a file or a link — to a payment. The method is independent of transfer confirmation: a receipt can be sent later, including when the payment is already cancelled or under dispute.

Endpoint

POST /v1/payments/{id}/receipt

Path Parameters

Parameter	Type	Description
id	string	Payment ID (UUID)

How to send

A receipt is sent either as a file or as a link. At least one is required.

File — multipart/form-data

Field	Type	Description
receipt	file	Receipt file. The names attachment, file, proof are also accepted
data	string (JSON)	Optional JSON part of the request

File limits: up to 10 MB, formats png, jpg, jpeg, webp, heic, pdf. The file is stored on our side and is available to the person reviewing the dispute.

Link — application/json

Parameter	Type	Description
receipt_url	string	Link to the receipt on your side

Example: file with a JSON part

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4/receipt \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: calculated-signature" \
  -F 'data={"comment":"receipt from the bank app"}' \
  -F "[email protected]"

Example: link

curl -X POST https://api.bopay.io/v1/payments/550e8400-e29b-41d4/receipt \
  -H "Content-Type: application/json" \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: calculated-signature" \
  -d '{"receipt_url":"https://your-site.com/receipts/12345.jpg"}'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ext_id": "order_12345",
  "status": "PENDING",
  "receipt_url": "/uploads/receipts/550e8400-e29b-41d4_20260827194512.png"
}

For an uploaded file receipt_url points to our storage; for an external receipt the link you sent is returned.

Allowed payment statuses

A receipt is accepted while the payment can still be reviewed: PENDING, DISPUTE, CANCELLED, CANCELLED_APPEAL. For a completed payment the method returns PAY_008.

If the payment is already under dispute, the receipt is also attached to the dispute card — but only when none was attached before; an earlier receipt is never overwritten.

Request signature

The signature is calculated as usual — HMAC-SHA1 over METHOD + URL + BODY, where BODY is the request body as is. For multipart/form-data that means the whole multipart body, including boundaries and file content.

Errors

Code	HTTP	Description
PAY_002	400	Neither a file nor receipt_url was sent, or the JSON part is invalid
PAY_006	404	Payment not found
PAY_008	400	A receipt cannot be attached in the current payment status
PAY_009	400	File is larger than 10 MB
PAY_010	400	Unsupported file format