Chargeback API

The Chargeback endpoints let you return money you received through PIX, in full or in part, and follow the outcome. They cover both cash in flows: payments received through a QR Code you generated, and PIX transfers received on your PIX key or on your branch and account number.

Which Endpoint to Use

There are two ways to point at the payment you want to refund. Pick the one that matches what your system stored.

What you have	Request the refund with	Check the status with
QR Code ID	`POST /v2/finance/chargebacks-pix-copy-and-paste`	`GET /v2/finance/chargebacks-pix-copy-and-paste/status`
Cash in transaction ID	`POST /v2/finance/chargeback`	`GET /v2/finance/chargeback/status`

The cash in transaction route accepts any PIX cash in you received, including payments that originally came from a QR Code. The QR Code route only accepts payments made against a QR Code you generated.

If you only have the EndToEndId, call GET /v2/finance/cashin/{e2e} first to get the cash in transaction ID.

Available Endpoints

Request a Chargeback by QR Code - Refund a payment using the QR Code ID
Check Chargeback Status by QR Code - Query the refund by chargeback ID or EndToEndId
Request a Chargeback by Cash In Transaction - Refund any received PIX using the cash in transaction ID
Check Chargeback Status by Cash In Transaction - Query the refund by chargeback ID

Chargeback Process

Identify the payment to be refunded (QR Code ID, or cash in ID from GET /v2/finance/cashin/{e2e})
Submit the refund request with the amount and the reason
Refund is settled - immediately when the payer's account is in the same institution, asynchronously otherwise
Track the status until it reaches SUCCESS or REJECTED
A webhook is delivered when the refund completes

Refund Amounts

Full - amount equals the value received
Partial - amount is lower than the value received
Multiple - several partial refunds are allowed while their sum does not exceed the value received

Status Values

Status	Description
PENDING	Refund accepted and being settled
SUCCESS	Refund completed and money returned to the payer
REJECTED	Refund could not be completed

Refunds of payments received from the same institution are settled immediately and already come back as SUCCESS. Everything else starts as PENDING.

Use Cases

Order cancellations and customer refunds
Returning a payment received in error
Partial refunds when only part of an order is returned
Resolving disputed charges

Limitations

Refunds are accepted for up to 90 days after the payment was received
The sum of all refunds cannot exceed the original amount
Only one refund can be in processing at a time for the same payment
The account must have enough available balance at the moment of the request
Closed accounts cannot send or receive a refund

Webhooks

Event	Trigger
`QR_CODE_COPY_AND_PASTE_REFUNDED`	Refund of a QR Code payment completed
`QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR`	Refund of a QR Code payment failed
`PIX_CASHIN_REFUNDED`	Refund of a received PIX transfer completed
`PIX_CASHIN_REFUNDED_ERROR`	Refund of a received PIX transfer failed

Best Practices

Use webhooks instead of polling the status endpoint
Always send a descriptive information field - it helps support and reconciliation
Store the returned chargeback id for later status queries
Check how much was already refunded before requesting a new partial refund
Expect PENDING and handle it: do not treat a non-SUCCESS first response as a failure