v1

latestOpenAPI 3.1.02026-08-0629140119.9 KB

PIX Refunds

Create Refund

Creates a refund request for a PIX transaction. The transaction_id must be provided in the request body. The refund will be processed asynchronously - validation and execution are performed by a worker process. If amount_in_cents is not provided, it defaults to 0 and will be determined during processing.

post/v1/refunds

Headers

X-Idempotency-Keystring nullable

Optional idempotency key for safe retries. When provided, requests with the same key and payload return the same result. Without this header, duplicate external_reference_id values will fail with 400 Bad Request.

Request body

amount_in_centsinteger nullable

Refund amount in centavos. Optional — if omitted, defaults to 0 and is determined during async processing.

external_reference_idstring nullable

Client-provided unique reference for this refund within the account (1–127 characters).

message_to_payerstring nullable

Message sent to the original payer (1–255 characters).

transaction_idinteger required

Identifier of the original PIX transaction to refund.

Example request

{
  "amount_in_cents": 15000,
  "external_reference_id": "refund-001",
  "message_to_payer": "Devolução parcial",
  "transaction_id": 123456789
}

Response

Refund request created successfully and will be processed asynchronously

cancelled_atstring date-time nullable

Cancellation timestamp (UTC, RFC 3339), if cancelled.

created_atstring date-time required

Refund creation timestamp (UTC, RFC 3339).

external_reference_idstring nullable

Client-provided reference identifier.

idinteger required

Refund identifier.

transaction_idinteger required

Original transaction identifier.

updated_atstring date-time required

Last update timestamp (UTC, RFC 3339).

Example response

{
  "cancelled_at": "2026-05-28T14:30:00Z",
  "created_at": "2026-05-28T14:30:00Z",
  "updated_at": "2026-05-28T14:30:00Z"
}