Cash-out
POST - https://dominio.com.br/api/cash-out-pixKey/
The Perform a Cash-out endpoint in the ENV Bank facilitates the initiation of a cash-out transaction, allowing users to withdraw funds from the platform.
⚠️Attention
From 10/01/2024, it will be mandatory to use the document_number parameter in the Perform a Cash-out endpoint. This parameter is used to validate whether the holder of the PIX key is the same holder of the document number provided.
document_number (string, mandatory): Mandatory parameter to validate ownership of the PIX key.
This update is essential to reinforce security in cash-out operations and ensure compliance with regulatory requirements.
✳️ Key type and its formats
The supported types are CPF, CNPJ, PHONE, EMAIL, and EVP. You must correctly specify the key in the "Key" field to ensure the transfer is made to the correct account. However, it is not necessary to explicitly specify the key type; just follow the standard format for each key, and the system will automatically identify the type:
CPF: Only numbers, 11 digits.
CNPJ: Only numbers, 14 digits.
Phone: Phone number in international format, including the country code, e.g., 5511999999999. ( “+” is required )
Email: A valid email address.
EVP: (Virtual Payment Address): A unique identifier provided by the bank or financial institution (UUID).
✅ Cash-out Status
CREATED: The cash-out request has been created.
PROCESSING: The cash-out request is being processed.
DONE: The cash-out request has been successfully processed and completed, with the funds transferred to the destination account.
REJECTED: The cash-out request was rejected due to some issue.
REFUNDED: The cash-out amount has been refunded to the customer.
PARTIALLY_REFUNDED: Part of the cash-out amount has been refunded to the customer.
FAILED: The cash-out request failed and could not be completed due to some issue. When this status is returned, it means the transaction was canceled, and a new transaction must be made.
➡️ Practical Tips
Pix Key Validation: Check that the Pix key and the holder's document are correct to avoid failures when executing the withdrawal.
Testing in the Sandbox Environment: Use Pix keys specific to the testing environment when simulating withdrawal operations.
🚧HEADERS
Authorization (string, required): The access token generated by the authentication endpoint must be included in the authorization header in the format Bearer {{access_token}}.
Body Params
key string required
Recipient's pix key
amount float required
Cash-out amount
document_number string
Optional. If you want to validate whether the PIX key holder is the same as the holder of the provided document number.
correlation_id string
Correlation id is sent in webhook's payload.
Exemplo:
curl --request POST \
--url https://dominio.com.br/api/cash-out-pixKey/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data '
{
"key": "emailchave@gmail.com",
"amount": 0.01,
"document_number": "xxxxxxxxxxxxxxx",
"correlation_id": "12RgfstRmnUqokjsjGtjjdn2447"
}
Resposta Positiva: RESPOSTA 200 JSON
{
"id": 189044566,
"refunds": [],
"idempotencyKey": "fbc9d29e-3ccd-4230-9446-d1793896s456",
"endToEndId": "E3720544720250814170123715b2e6c1",
"pixKey": "xxxxxxxxxxxxxxxxxxxxxxxx",
"payment": {
"currency": "BRL",
"amount": 0.01
},
"status": "CREATED",
"transactionType": "PIX",
"localInstrument": "DICT",
"createdAt": "2025-08-14T17:01:23.864+00:00",
"creditorAccount": {
"ispb": "31872495",
"document": "xxxxxxxxxxxxxxxx",
"name": "xxxxxxxxxxxxxxxxxxxxxxxxx",
"number": "0000",
"issuer": "0000",
"accountType": "CACC"
},
"debtorAccount": {
"ispb": "37205447",
"document": "61962430000189",
"name": "ENV BANK",
"number": "0000",
"issuer": "0000",
"accountType": "TRAN"
},
"remittanceInformation": null,
"errorCode": null,
"txId": null,
"creditDebitType": "DEBIT",
"correlation_id": "14RgfstRmnUqokjsjGtjjdn23456"
}
Resposta ERRO:
RESPOSTA 400
{"error_code":"AC004","reason":"A requisição que busca alterar ou criar uma cobrança para pagamento imediato não respeita o schema ou está semanticamente errada."}
RESPOSTA 403 Forbidden
{"error_code":"AC005","reason":"Requisição de participante autenticado que viola alguma regra de autorização."}
RESPOSTA 404
{"error_code":"AC006","reason":"Entidade não encontrada."}
RESPOSTA 503
{"error_code":"AC006","reason":"Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."}
