Refund PIX Transaction


  • Only CREDIT transactions can be refunded, either partially or fully.
  • A single CREDIT transaction may undergo multiple partial refunds, provided the total refund amount does not exceed the original transaction value.
  • Refunds can be executed within 90 days following the original CREDIT transaction date.

How to Refund a PIX Transaction

To initiate a refund, call the Refund Transaction Endpoint endpoint. The code snippet below demonstrates how to make the request with the necessary headers and payload:

curl --request POST\
  --url{transactionId}/refund \
  --header 'authorization: Bearer {accessToken}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '
  "amount": {
    "value": 10000
  "motive": "PROCESSING_ERROR",
  "idempotentId": "24b2ae17-5a58-4465-acbb-45e11fdc2496",
  "additionalInfo": "Client canceled the purchase"


  • Replace {transactionId} path parameter with the ID of the CREDIT transaction you wish to refund.
  • The idempotentId is a unique identifier to prevent duplicate refund requests.
  • The additionalInfo field is optional and may be used to provide context for the refund request to the banking team.

Refund Types

  • If the amount field is omitted or set as null, a full refund is processed, changing the original transaction status to REFUNDED, and creating a new REFUND transaction.
  • If a specific amount is specified, a partial refund is initiated. The original transaction's status becomes PARTIALLY_REFUNDED, and a new REFUND transaction is formed. Once the combined value of all partial refunds equals the original transaction's value, its status updates to REFUNDED.


Upon initiating a refund, TraceFinance sends out specific webhooks to facilitate transparent and real-time tracking of the transaction status:

  • A TRANSACTION_REFUNDED is dispatched when a refund process commences.
  • A TRANSACTION_CREATED is issued for a new REFUND transaction, including the originalTransactionId for tracking purposes.
  • A TRANSACTION_COMPLETED is sent once the REFUND transaction is successfully processed, marking the completion of the refund operation.