Request Withdrawal

Requests a withdrawal from the company's available balance. If the request includes a PIX key (pixKey), that key takes priority.

POST/api/Withdraw/request

Headers

Header	Value	Status
Content-Type	application/json	Required
Accept	application/json	Required
X-Client-Id	<client_id>	Required
X-API-Key	<api_key>	Required
X-Operation-Token	<token with scope cashout:create>	Required

The X-Operation-Token header is required and must be generated at POST /api/v1/operation-auth/token with scope cashout:create. See Authentication for details.

Note

If pixKey is omitted, the system automatically uses the PIX key registered on the company's bank account (BankAccount).

Request Body

Body

{
  "amount": 2500,
  "currency": "BRL",
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "description": "Test withdrawal to a custom key",
  "metadata": { "source": "n8n", "orderId": 123 }
}

Parameters

Parametro	Tipo	Descricao
`amount`*	number	Amount in cents (2500 = R$ 25.00)
`currency`*	string	Currency (BRL)
`pixKey`	string	Destination PIX key (optional)
`pixKeyType`	string	Key type: CPF, CNPJ, EMAIL, PHONE, EVP
`description`	string	Withdrawal description
`metadata`	object	Extra data for your reference

amount

Obrigatorionumber

Amount in cents (2500 = R$ 25.00)

currency

Obrigatoriostring

Currency (BRL)

pixKey

string

Destination PIX key (optional)

pixKeyType

string

Key type: CPF, CNPJ, EMAIL, PHONE, EVP

description

string

Withdrawal description

metadata

object

Extra data for your reference

Response

Important Rule

The response only tells you whether the request was created or failed to be created. There is no pending, awaiting or processing in the creation response. Those statuses belong to tracking through the webhook, the provider or PIX settlement.

Success

HTTP 201Created

Response 201

{
  "success": true,
  "status": "success",
  "message": "Pedido de saque criado com sucesso.",
  "id": 12345,
  "companyId": 10,
  "idempotencyKey": "wd_test_pix_custom",
  "value": 25.00,
  "pixKey": "********",
  "pixKeyType": "CPF",
  "creditorDocument": "********",
  "description": "R$25 withdrawal to a custom key",
  "currency": "BRL",
  "createdAt": "2026-06-14T16:50:00Z"
}

Success Fields

Parametro	Tipo	Descricao
`success`	boolean	Always true when the request was created.
`status`	string	Always success when the request was created.
`message`	string	Creation confirmation message (in Portuguese).
`id`	number	Internal ID of the withdrawal request.
`companyId`	number	Company ID.
`idempotencyKey`	string	Idempotency key sent in the Idempotency-Key header.
`value`	number	Net withdrawal amount in reais.
`pixKey`	string	PIX key used as the destination.
`pixKeyType`	string	PIX key type: CPF, CNPJ, EMAIL, PHONE or EVP.
`creditorDocument`	string	Beneficiary's document.
`description`	string	Description sent in the request.
`currency`	string	Withdrawal currency. Currently BRL.
`createdAt`	string	Date/time the request was created.

success

boolean

Always true when the request was created.

status

string

Always success when the request was created.

message

string

Creation confirmation message (in Portuguese).

id

number

Internal ID of the withdrawal request.

companyId

number

Company ID.

idempotencyKey

string

Idempotency key sent in the Idempotency-Key header.

value

number

Net withdrawal amount in reais.

pixKey

string

PIX key used as the destination.

pixKeyType

string

PIX key type: CPF, CNPJ, EMAIL, PHONE or EVP.

creditorDocument

string

Beneficiary's document.

description

string

Description sent in the request.

currency

string

Withdrawal currency. Currently BRL.

createdAt

string

Date/time the request was created.

Failure

When the API cannot create the withdrawal request, it returns an HTTP error. In those cases the request must not be considered created.

HTTP	Result	Example cause
400 Bad Request	Not created	Missing body, invalid amount, insufficient balance, invalid PIX key.
401 Unauthorized	Not created	Invalid operation token.
403 Forbidden	Not created	Invalid credentials, company not allowed, or IP not on the whitelist.
409 Conflict	Not created	Idempotency conflict.
500 Internal Server Error	Not created	Internal error while requesting the withdrawal.

Error Examples

Missing body

400

{
  "message": "Body ausente."
}

Invalid amount

400

{
  "message": "Amount invalido (deve ser > 0, em centavos)."
}

Missing Idempotency-Key

400

{
  "message": "Header Idempotency-Key e obrigatorio."
}

Invalid operation token

401

{
  "title": "Token de operacao invalido.",
  "detail": "Token invalido ou expirado.",
  "header": "X-Operation-Token"
}

Unauthorized IP

403

{
  "title": "IP nao autorizado.",
  "detail": "O IP 177.123.45.67 nao esta na whitelist desta empresa."
}

Internal error

500

{
  "message": "Erro ao solicitar saque."
}

How to Integrate

Rely only on the HTTP status and the status field of the creation response.

Integration rule

HTTP 201 + status "success" = request created
HTTP 400/401/403/409/500 = request not created

Do not wait for a second HTTP response to the same request. If the withdrawal changes state later, that update comes through the webhook or a status lookup.

cURL Example

cURL

# 1. First, generate the operation token
TOKEN=$(curl -s -X POST https://baanko.app/api/v1/operation-auth/token \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -d '{"scopes": ["cashout:create"]}' | jq -r '.token')
# 2. Request the withdrawal with the token
curl -X POST 'https://baanko.app/api/Withdraw/request' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: <CLIENT_ID>' \
  -H 'X-API-Key: <API_KEY>' \
  -H "X-Operation-Token: $TOKEN" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "description": "R$10 withdrawal to a custom key",
    "metadata": { "source": "n8n", "orderId": 123 }
  }'