Pedir saque

Manda o saldo disponível por Pix para a chave que você envia no pedido (SAQ-API-).

POST /v1/withdrawals

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/withdrawals \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: saque-2026-10-08-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000, "destination": { "keyType": "cpf", "key": "123.456.789-09" }, "description": "Fechamento do dia" }'

200

{
  "id": "SAQ-API-3F7K9Q2W8M4Z",
  "status": "processing",
  "amount": 50000,
  "fee": 50,
  "total": 50050,
  "channel": "api",
  "destination": { "name": "Ana S.", "institution": "Banco Exemplo", "keyType": "cpf", "key": "***.456.789-**" },
  "endToEndId": null,
  "failureReason": null,
  "createdAt": "2026-10-08T15:10:00.000Z",
  "completedAt": null
}

Escopo withdrawals:write, 2FA ligado na conta e IP liberado na chave de API. O saque vai para a chave Pix que você manda no pedido (destination) ou para o recebedor de um Pix Copia e Cola (copyPaste), só um dos dois. Não precisa cadastrar a chave antes. Limite de 20 pedidos por minuto.

Idempotency-Key · string · required

8 a 128 caracteres, única por saque. Repetir com os mesmos dados devolve o mesmo saque.

amount · integer · required

Valor em centavos que chega na chave. A tarifa sai além desse valor (total). A partir do mínimo da conta (BELOW_MINIMUM).

destination · object

A chave Pix que vai receber. Sem destination e sem copyPaste: 422 DESTINATION_REQUIRED.

Show propriedades

keyType · string · required

cpf, cnpj, email, phone ou random.

key · string · required

A chave (3 a 77 caracteres).

copyPaste · string

Pix Copia e Cola: o saque vai para a chave do código. Se o código tem valor, amount precisa ser igual (AMOUNT_MISMATCH).

description · string

Até 140 caracteres, para o seu extrato.

​

Resposta

id · string

SAQ-API- + 12.

status · string

processing (em andamento). Depois: completed, failed ou rejected.

amount · integer

O que chega na chave.

fee · integer

Tarifa.

total · integer

amount + fee, o que saiu do saldo.

channel · string

api.

destination · object

Show propriedades

name · string | null

Titular da chave.

institution · string | null

Banco.

keyType · string

cpf, cnpj, email, phone ou random.

key · string

Chave sempre mascarada.

endToEndId · string | null

Identificador do Pix, preenchido quando concluído.

failureReason · string | null

Motivo quando failed ou rejected.

createdAt · string

Pedido.

completedAt · string | null

Conclusão.

Se você tem subcontas, o que é delas não sai no seu saque: passando disso, 422 SUBACCOUNT_FUNDS (a mensagem diz quanto dá para sacar). GET /v1/balance mostra subaccounts e free.

A resposta não é a conclusão. Espere o webhook withdrawal.completed (ou withdrawal.failed) ou consulte o saque antes de considerar o dinheiro entregue.

cURL

curl -X POST https://bukio-backend-production.up.railway.app/v1/withdrawals \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: saque-2026-10-08-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000, "destination": { "keyType": "cpf", "key": "123.456.789-09" }, "description": "Fechamento do dia" }'

200

{
  "id": "SAQ-API-3F7K9Q2W8M4Z",
  "status": "processing",
  "amount": 50000,
  "fee": 50,
  "total": 50050,
  "channel": "api",
  "destination": { "name": "Ana S.", "institution": "Banco Exemplo", "keyType": "cpf", "key": "***.456.789-**" },
  "endToEndId": null,
  "failureReason": null,
  "createdAt": "2026-10-08T15:10:00.000Z",
  "completedAt": null
}