Saldo e saques
Pedir um saque
Pede um saque do saldo disponível para a sua chave Pix ativa. O valor fica reservado até a análise.
POST
/v1/withdrawals Requer o escopo WITHDRAWAL:CREATE
O saque vai para a sua chave Pix ativa. Cadastre a chave antes em Cadastrar a chave Pix de saque. Veja como funciona em Saldo e saques.
O valor que você pede é o que sai do seu saldo. A taxa de saque é descontada dele e você recebe o restante. Para saber o valor exato antes de pedir, use Simular um saque.
Requisição
Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount_cents | integer | sim | Quanto sai do seu saldo, em centavos. A taxa é descontada deste valor. Precisa estar entre o mínimo e o máximo por saque da sua conta. |
expected_net_cents | integer | null | não | O valor líquido que você conferiu (o net_cents de Simular um saque). Se a taxa mudou nesse meio tempo, o saque não é feito e a API responde 409 fee_changed com a simulação nova. |
Resposta
A API responde 201 com o saque em requested.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Id do saque. |
status | string | Status do saque. Veja os status. |
amount_cents | integer | Quanto saiu do seu saldo, em centavos. |
fee_cents | integer | Taxa do saque, em centavos. Já está dentro de amount_cents. |
net_cents | integer | Quanto chega na sua chave Pix: amount_cents menos fee_cents. |
reason | string | null | Por que o saque foi recusado. null nos outros casos. |
payout_key | string | A chave Pix que recebe o saque, mascarada. |
created_at | string (ISO 8601) | Quando o saque foi pedido. |
paid_at | string (ISO 8601) | null | Quando o saque foi pago. |
Erros
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 409 | payout_key_required | Você ainda não tem chave Pix de saque ativa. | Cadastre a chave. |
| 409 | daily_limit_exceeded | O saque passa do limite do dia. | Peça um valor menor ou espere o próximo dia. |
| 409 | insufficient_balance | O saldo disponível não cobre o valor pedido. | Consulte o saldo. |
| 409 | fee_changed | A taxa mudou e o líquido não é mais o expected_net_cents enviado. Nada foi reservado. | Confira a simulação nova em detail e peça de novo com o líquido novo e uma nova Idempotency-Key. |
| 503 | withdrawals_unavailable | Saques estão indisponíveis no momento. Nada foi reservado. | Tente mais tarde. |
| 422 | validation_failed | Valor fora do mínimo ou do máximo por saque, ou menor que a taxa (amount_below_fee). | Veja o campo fields. |