Create PIX QR Code Chargeback

This API allows you to request a chargeback (full or partial) for a PIX payment made via QR Code. The chargeback processing is asynchronous and the status can be consulted later through the Chargeback Status API.

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "qr_code_id": 12345,
  "amount": 100.50,
  "information": "Devolução solicitada pelo cliente"
}

Field	Type	Description	Required or Optional
qr_code_id	Integer	ID of the QR Code that will be refunded. This is the unique identifier returned when creating the QR Code.	required
amount	Decimal	Chargeback amount (must be greater than 0, with 2 decimal places). The amount can be equal to or less than the QR Code value, but the sum of all chargebacks cannot exceed it.	required
information	String	Reason/information for the chargeback. This is a descriptive text field to document why the chargeback is being requested.	required

Response Details

{
  "worked": true,
  "id": 67890,
  "end_to_end_id": "E123456789abcdef",
  "amount": 100.50,
  "status": "PENDING",
  "fee": 0.00
}

Field	Description
worked	Returns true or false confirming whether the chargeback request was successfully submitted or not.
id	Unique chargeback identifier generated. This value never repeats, and it enables querying endpoints to confirm the chargeback status.
end_to_end_id	UUID (Universally Unique Identifier) of the chargeback. This identifier can be used to query the chargeback status and for reconciliation purposes.
amount	Returns the chargeback amount (the same information that was sent in the body)
status	PENDING - Chargeback is being processed. The status should be consulted later using the Chargeback Status endpoint. SUCCESS - Chargeback successfully completed (typically for internal transfers between accounts of the same institution)
fee	This field returns the fee charged to the Simpay customer when using the Chargeback endpoint (default: 0.00)

Error Responses

HTTP Code	Error Message	Description
400	QR Code not found	The QR Code was not found or does not belong to your company. Verify the qr_code_id and authentication token.
400	QR Code is not paid	The QR Code status is not PAID or CHARGEBACK. Only paid QR Codes can be refunded.
400	There is a refund in processing	There is already a chargeback with PENDING status for this QR Code. Wait for the previous chargeback to complete before creating a new one.
400	Amount is greater than the value of the QR Code	The chargeback amount exceeds the available balance. Check the original QR Code value and subtract any previous chargebacks.
400	Cannot process chargeback for closed account	The account associated with this QR Code is closed. Chargebacks cannot be processed for closed accounts. Contact support if you need further help.

Business Rules

Validations:

QR Code must exist and belong to the authenticated company
QR Code status must be PAID or CHARGEBACK
Cannot have another chargeback with PENDING status for the same QR Code
Amount must be greater than 0 and not exceed the available balance (original value minus previous chargebacks)
The associated account cannot be closed

Chargeback Types:

Full Chargeback: Amount equals the total value of the QR Code
Partial Chargeback: Amount is less than the total value of the QR Code
Multiple Chargebacks: Multiple partial chargebacks can be created as long as the sum does not exceed the original QR Code value

Processing:

Internal Chargeback (same institution): Synchronous processing with immediate SUCCESS status
External Chargeback (other institutions): Asynchronous processing with PENDING status. Use the Chargeback Status endpoint to track completion.