Refund PIX Transaction

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"
}
'

Parameters:

• 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.

Webhooks

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

• 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.
• A TRANSACTION_REFUNDED is dispatched for the original transaction when the process has been completed.