Guides
Dashboard

Refund PIX Transaction

Suggest Edits

Introduction

  • 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 https://faas.sandbox.tracefinance.io/pix/api/transactions/{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",
  "bankAccountId": "9008369c-8837-43c7-b5f2-0229622bd21c"
}
'

Parameters:

  • {transactionId} refers to the ID of the CREDIT transaction that you wish to refund. (required)
  • idempotentId is a unique identifier to prevent duplicate refund requests. (required)
  • additionalInfo is an open field to provide context for the refund request to the banking team. (optional)
  • bankAccountIdis the bank account designated to receive the PIX transaction. This information is required only if you have more than one bank account. (conditionally required)

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.

What Happens Next

When a refund is requested for a transaction, a Debit Refund Transaction is created, triggering the following events:

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

After the Debit Refund Transaction is completed, the original credit transaction that was refunded will have its status updated to either REFUNDED or PARTIALLY_REFUNDED (in cases where the refunded amount was partial).

Updated 2 months ago