Refunds

Use refunds to return all or part of a received Pix payment. The refund uses the original charge and returns the money to the account that made the payment; you do not need to provide another customer, destination account or Pix key.

When to request a refund

The charge must have a received and confirmed Pix payment. In Production, the original transfer must be identified. In Sandbox, use a payment confirmed by Raims simulation. A partially refunded charge can receive another request for the remaining amount after the previous one completes. The amount must be covered by the account available balance.

Accepted statuses are 4 (paid) and 5 (partially_refunded). Being in one of these statuses does not remove the other conditions, such as an identified Pix payment, remaining amount and available balance.

A charge accepts only one refund in progress. If a request is already pending or has no confirmed result, track that request before trying another. The eligibility query shows the current restriction.

A dispute under review can also prevent a request. In that case, check the charge disputes; there may be no refund in progress in the history.

This resource refunds Pix payments. Unpaid charges use revocation. The refund endpoint does not refund boleto payments or accept instructions to transfer to another account.

Check the refundable amount

Use Check refund eligibility, with GET /v1/charges/{id}/refund_eligibility, before offering a refund. Provide the charge identifier with the ch_ prefix.

eligible indicates whether current conditions allow a request. refundable_amount_cents shows how much remains to be refunded on the charge. max_refund_amount_cents shows the maximum you can request now, considering that remainder and the available balance, and is zero when a restriction applies. pending_amount_cents shows the amount of requests awaiting a result.

When a restriction applies, reason gives its code and an explanation in English. Use reason.code to decide how to handle it; reason.message is for diagnostics and its wording may improve. Without a restriction, reason is null.

If R$100.00 remains on the charge and R$40.00 is available for a refund, refundable_amount_cents is 10000 and max_refund_amount_cents is 4000. At that point, you can request up to R$40.00. This field does not show the full account balance.

Send a positive amount_cents, up to the stated maximum. To refund the entire remainder, the available maximum must cover the remaining charge amount. This query does not set aside the money or guarantee acceptance: conditions can change and are checked again when submitting the refund.

Refund a Pix payment through the API

Use Request a refund, with POST /v1/charges/{id}/refunds, and send amount_cents. The amount uses whole cents: for example, 2500 represents R$25.00. description lets you record an optional description of the request.

{
  "amount_cents": 2500,
  "description": "Devolução parcial do serviço"
}

To refund everything, send the remaining amount in amount_cents. Omitting this field is invalid. For a partial refund, send the partial amount in the same request. The customer and destination account come from the original payment; do not send banking details or a Pix key.

In Production, a 202 response confirms that the request was accepted for tracking. In Sandbox, the simulation completes within the request and returns 200 with status: completed. Keep the refund id, with the rf_ prefix, to check its result. It differs from the charge ch_ identifier.

If you lose the response, check the charge history before repeating the request. A new request may represent another partial refund.

Track the result

Use Retrieve a refund, with GET /v1/refunds/{id}, to query the same request. The response shows the linked charge, amount, description, current status and available dates. When the status is failed, failure_reason explains the confirmed failure with a code and a message in English.

A pending request does not yet confirm that the money returned to the payer. Consider the refund complete only when the returned status confirms completion. After a failure, check the request and charge eligibility before deciding on a new request.

created_at, completed_at and failed_at use Unix seconds in UTC. Completion and failure dates are null until the corresponding result is confirmed. Repeated queries do not start or speed up a refund.

Use failure_reason.code to handle the known cause. The message is for diagnostics and may improve without changing the meaning of the code. For other statuses, failure_reason is null. An older failure with no recorded cause may show an unknown reason; this does not justify assuming bank rejection or automatically creating another request.

View the history

Use List refunds, with GET /v1/refunds, to view requests for all charges in the company and environment of the key. Each item includes charge_id, allowing you to associate the refund with the charge in your system.

To track partial refunds for a specific charge, use List refunds for a charge, with GET /v1/charges/{id}/refunds. Both lists show newest requests first and include pending, completed and failed requests.

In both lists, use created_gte and created_lte to filter the period when the refund was requested. Provide Unix seconds in UTC; boundaries are inclusive. This period considers created_at, not the charge payment date or refund completion. You can provide one boundary or both, with the end equal to or later than the start.

The response uses list and page. Start without a cursor, process list and copy page.next_after to after while page.has_next is true. Keep the same key, filters and list throughout navigation; for the list by charge, also keep the same id. To query another period, start without a cursor. Do not interpret or change the received cursor, or exchange cursors between the two lists.

To view a previous page, use page.previous_before in before. Do not send after and before together. See Listing and pagination for the general rules.

Refund receipt

Use Download a refund receipt, with GET /v1/refunds/{id}/receipt, to save the document or make it available to the customer. Provide the refund identifier with the rf_ prefix, received in the request or history query.

The receipt requires status: completed, a positive amount and a recorded completion date. Pending, failed or unconfirmed requests do not have a completion receipt. In those cases, track the same refund in Retrieve a refund.

The PDF shows the amount of that refund. If a charge has two partial refunds, each request has its own receipt; the document does not total the history or replace the original charge amount.

The endpoint returns JSON with url and expires_at. Call it from your integration server with the API key. Make a GET request to the complete url to download the PDF from files.raims.com, without sending Authorization or the API key in that download. expires_at gives the expiration in Unix seconds in UTC. After it expires, query the authenticated endpoint again to get another link. An invalid or expired link may receive HTTP 403 on download, without the API JSON error envelope.

The URL can be reused until it expires and grants access to anyone who has it. Share it only with authorized people and do not record it in logs. The document is issued by Raims and does not replace a tax invoice or bank receipt. A Sandbox receipt identifies the refund as a simulation, with no real money movement.

Pix refunds through the API: Sandbox and Production

Sandbox lets you test full and partial refunds using the same endpoint and fields as Production. First, confirm a Pix payment through Confirm payment or the Dashboard simulation. Use a Sandbox key from the same company to check eligibility and request a refund.

The simulation considers available balance and the remaining amount, completes within the request and returns 200 with status: completed. The Sandbox charge, refund history, balance and statement reflect the simulated refund. No real money moves. This documentation console accepts only Sandbox keys.

To test a request awaiting a result, use Simulate a pending refund. Then choose between completing the refund and simulating a failure using the same refund ID. This lets you check tracking, balance and receipt availability. See Pending and failed Pix refunds.

Accepted statuses and other conditions still apply; boleto does not support refunds through this endpoint. Confirmed changes generate events for Sandbox webhooks registered for those types. In Production, an accepted request can return 202 while awaiting confirmation, which must be tracked by querying the refund.

Requests use https://api.raims.com and require an API key. You do not need to enable an additional refund permission on that key. The employee Refund Pix permission authorizes the action in the Dashboard; it is not required for API requests.

The company and environment come from the key; an identifier from another company or environment does not grant access to the charge or refund.