Response

This page describes the possible responses when initiating a Pix withdrawal via the Withdraw API

201 Created - Withdrawal successfully initiated

The request was accepted and payment processing has been initiated. The 201 response confirms only that the transaction was received and queued, it does not mean the transfer has been completed. The final outcome (success or failure) will be delivered asynchronously via webhook.

JSON

{
  "transactionId": "00000005",
  "responseStatus": "200"
}

Field reference

Field	Type	Description
transactionId	string	Unique identifier for the withdrawal transaction. Use this value to correlate the initial request with the corresponding webhook callback.
responseStatus	string	Indicates the processing result of the request. A value of "200" confirms the transaction was successfully received.

Important: A 201 Created response does not guarantee that the Pix transfer was completed. Always rely on the Webhook notification to determine the final status of the transaction.

---

400 Bad Request - Withdrawal creation failed

The request was rejected. The message field describes the reason for the error.

All error responses follow the same envelope:

JSON

{
  "name": "WithdrawCreateError",
  "message": ["<error description>"]
}

Possible errors

Message	Cause	How to resolve
"Identificador de transação já utilizado, favor utilizar outro."	The transactionId submitted was already used in a previous withdrawal.	Generate a new unique transactionId before resubmitting the request.
"Erro desconhecido. Caso persista, contate o suporte."	Unidentified internal failure.	Retry the request. If the error persists, contact technical support.

---

Next steps: Configure a Webhook endpoint to receive the final status of each withdrawal asynchronously. You can also request a Proof of transfer once the transaction is completed.