Request a refund for a received Pix

A refund for a Pix can be processed up to 90 days from its receipt.

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer/PIX_TRANSFER_KEY/reversal

METHOD

POST

Path Params

Field	Type	Description	Characters
account_key *	uuidv4	Unique identification key of the account.	36
pix_transfer_key *	uuidv4	Unique identification key of the Pix transfer in the QI system.	36

Request Body

{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Refund Pix message"
}

Request Body

Field	Type	Description	Characters
request_control_key *	uuidv4	Uniqueness key for the request.	36
reversal_amount *	number	Refund amount.	11
reversal_reason *	string	Reason for the refund.	Enumerator reversal_reason
reversal_message	string	Refund message.	140

Enumerator reversal_reason

Enumerator	Description
client_request	When requested by the account owner.
reconciliation	For reconciliation due to operational error.

Response

STATUS

201

Response Body: Refund Sent

{
  "reversal_status": "sent",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

STATUS

202

Response Body: Refund Pending

{
  "reversal_status": "pending",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

Information

If HTTP Status 202 is returned with the pix_transfer_status field having the value pending, the Pix request should not be retried.

This transfer will be reprocessed. The transfer status needs to be checked through the Pix Transfer Status Query.

Response Body

Field	Type	Description	Characters
reversal_status	enumerator	Enumerator of the refund transaction status.	Enumerator reversal_status
transfer_amount	number	Refund transfer amount.	11
pix_transfer_key	uuidv4	Key of the executed Pix refund transaction.	36
end_to_end_id	string	Idempotency key of a Pix transaction within the SPI (Instant Payment System)	32
request_control_key	uuidv4	Unique identification key of the request used by the client.	36
created_at	string	Date and time of the refund.	10

Enumerator reversal_status

Enumerator	Description
sent	Pix transfer successfully completed.
pending	Pix transfer pending.
rejected	Pix transfer rejected.

STATUS

4xx

Response Body: Refund Rejected

{
  "title": "title",
  "description": "description in English",
  "translation": "description in Portuguese",
  "code": "code",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}

Information

In addition to the errors previously listed for Pix transfer, the refund of a Pix can also return the errors listed below.

HTTP Code status	QI Code code	Title title	Description (eng) description	Description (ptbr) translation
400	QIT000001	Bad Request	Schema Error	Erro de Schema
404	PXT000018	Reversal Original Transfer not Found	Reversal original pix transfer not found.	Transferência original da devolução não foi encontrada.
400	PXT000017	Reversal Too Great	Reversal transfers sum amount surpasses that of original pix transfer.	A soma das transferências de devolução ultrapassam o valor da transferência pix original.
400	PXT000015	Reversal date expired	Reversal original transaction is older than 90 days	A data de criação da transação original é mais antiga que 90 dias
400	PXT0000127	Invalid Reversal Reason	Reversal reason {reversal_reason} is not valid	Razão de reversão {reversal_reason} não é válida