Saques

Tire o saldo da conta para a chave Pix que você envia, com idempotência e acompanhamento.

O saque (SAQ-API-) manda o saldo disponível por Pix para a chave Pix que você envia no pedido (destination) ou para o recebedor de um Pix Copia e Cola (copyPaste). Não precisa cadastrar a chave antes: as chaves favoritas do painel são só um atalho de quem saca pela tela. Como a chave de API pode mandar dinheiro para qualquer chave, ela só funciona com o 2FA ligado na conta e dos IPs que você liberou.

Exige o escopo withdrawals:write, o 2FA ligado na conta e pelo menos um IP liberado na chave de API. Chamada de outro IP responde 403 IP_NOT_ALLOWED.

Para pagar alguém ou um Pix Copia e Cola, use o saque. A rota antiga POST /v1/pix/payments (Pix enviado, ENV-) vai ser removida: ela ainda funciona para quem já usa e responde com os cabeçalhos Deprecation: true e Link: </v1/withdrawals>. Troque pela POST /v1/withdrawals, que faz o mesmo (chave ou Copia e Cola, mesma tarifa) e avisa pelos webhooks withdrawal.*.

​

Pedir um saque

POST /v1/withdrawals · escopo withdrawals:write · Idempotency-Key obrigatória

amount · integer · required

Valor em centavos que vai chegar na chave. A tarifa é descontada além desse valor (total na resposta).

destination · object

{ "keyType": "cpf" | "cnpj" | "email" | "phone" | "random", "key": "..." }: a chave que vai receber.

copyPaste · string

No lugar de destination: um Pix Copia e Cola (o saque vai para a chave do código; se ele tem valor, amount precisa ser igual).

description · string

Até 140 caracteres, para o seu extrato.

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" }'

​

Resposta

{
  "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
}

status	O que significa
processing	em andamento. Valor e tarifa já saíram do saldo e ficam reservados até o fim; você recebe withdrawal.completed ou withdrawal.failed
completed	caiu na chave; endToEndId e completedAt preenchidos
failed · rejected	não realizado (failureReason diz o motivo); valor e tarifa voltam ao saldo

A resposta da criação não é a conclusão: espere o webhook withdrawal.completed ou consulte o saque.

​

Regras

• Valor mínimo por saque: o da sua conta (padrão R$ 1,00; GET /v1/balance mostra em withdrawal.minPerTransaction): BELOW_MINIMUM.
• Precisa ter amount + fee disponível: INSUFFICIENT_FUNDS.
• O que é das suas subcontas não sai no seu saque (só no saque da própria subconta): SUBACCOUNT_FUNDS. GET /v1/balance mostra subaccounts e free.
• Sem chave no pedido, ou com mais de uma forma: DESTINATION_REQUIRED. pixKeyId (favorita) não vale na API.
• Chave de conta WyzeCash não é destino de saque: INTERNAL_ACCOUNT.
• Com a verificação de cadastro obrigatória e a sua conta ainda sem aprovação: 403 KYC_REQUIRED (cobranças continuam).
• Em manutenção: 503 MAINTENANCE (receber continua).

​

Consultar e listar

Método	Rota	Escopo	O que faz
GET	/v1/withdrawals/{id}	transactions:read	um saque (SAQ- ou SAQ-API-)
GET	/v1/withdrawals?limit=&cursor=	transactions:read	saques, do mais novo para o mais antigo

​

Saque automático

Se preferir não programar, o painel tem regras de saque automático (ao atingir um valor ou todo dia num horário, com % do disponível), até 5 por conta, cada uma para a chave digitada nela. Os saques gerados chegam pelos mesmos webhooks withdrawal.*, com channel: "auto".