# Saques Pix (/docs/conta-digital/withdrawals)
O valor que você pede é o que chega ao destino; a tarifa é somada por cima. Os dois saem do saldo disponível na hora do pedido e voltam se o saque falhar.
### Conferir quem recebe [#conferir-quem-recebe]
Opcional. Para mostrar o titular da chave antes de confirmar, use [Consultar destinatário](/docs/conta-digital/recipient).
### Pedir o saque [#pedir-o-saque]
[`POST /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/post_withdraw), escopo `WITHDRAW`. Obrigatórios: `amount`, em centavos, e `pixKey`, a chave de destino.
Gere uma `Idempotency-Key` para cada saque e guarde com o seu registro. Repetir a chamada com a mesma chave devolve o saque que já existe, sem enviar outro Pix.
```bash
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/withdraw \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"pixKey": "fulano@exemplo.com",
"pixKeyType": "EMAIL",
"comment": "Repasse semanal"
}'
```
```ts
import crypto from 'node:crypto';
const idempotencyKey = crypto.randomUUID();
const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 10000,
pixKey: 'fulano@exemplo.com',
pixKeyType: 'EMAIL',
comment: 'Repasse semanal',
}),
});
const saque = await res.json();
```
Mande também `pixKeyType` (`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`). Sem ele, o tipo é deduzido do formato, e um celular de 11 dígitos pode ser lido como CPF. Tipo que não bate com a chave é recusado com `400` `WITHDRAW_PIX_KEY_TYPE_MISMATCH`, e nada sai do saldo.
`comment` vai ao destinatário quando o banco dele exibe. `callbackUrl` recebe os webhooks deste saque e exige o [segredo de callback](/docs/conta-digital/webhooks#callbackurl-da-operação). Todos os campos estão em [Sacar para chave Pix](/docs/conta-digital/endpoints/withdrawals/post_withdraw).
### Guardar o saque [#guardar-o-saque]
A resposta (`201`) traz o saque. Guarde o `id`.
```json
{
"id": "hubp-20261005R4D8TN2WQZ127431",
"status": "APPROVED",
"amount": 10000,
"serviceFee": 250,
"totalDebited": 10250,
"pixKey": "fulano@exemplo.com",
"comment": "Repasse semanal",
"e2e": null,
"providerRejectedReason": null,
"callbackUrl": null,
"createdAt": "2026-10-05T14:40:11.002Z",
"sentAt": "2026-10-05T14:40:11.380Z",
"approvedAt": "2026-10-05T14:40:11.702Z",
"confirmedAt": null
}
```
`totalDebited` é o que saiu da conta: `amount` + `serviceFee`. Com tarifa de 1,5% + R$ 1,00, um saque de R$ 100,00 debita R$ 102,50.
### Confirmar a entrega [#confirmar-a-entrega]
O saque está entregue quando chega o webhook `WITHDRAW_COMPLETED`, com `status: "CONFIRMED"`. Se falhar, chega `WITHDRAW_FAILED`.
Para conferir a qualquer momento, consulte [`GET /transactions/withdraw/{withdrawId}`](/docs/conta-digital/endpoints/withdrawals/get_withdraw), escopo `WITHDRAW_READ`, com o `id` da resposta ou o `withdrawId` do webhook.
Na consulta e na listagem, a chave vem em `destination.pixKey`, mascarada quando é CPF, e-mail ou telefone. Só a resposta do `POST` traz `pixKey` na raiz.
## Status do saque [#status-do-saque]
| Status | Significado |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `REQUESTED` | Pedido recebido. O valor e a tarifa já saíram do saldo disponível. |
| `CREATED` | Registrado no banco. |
| `APPROVED` | Aprovado, a caminho. Ainda não é dinheiro entregue. |
| `CONFIRMED` | O dinheiro chegou. Webhook: `WITHDRAW_COMPLETED`. |
| `FAILED` | Não saiu, e o valor e a tarifa voltaram ao saldo. Pode vir de qualquer status anterior. Webhook: `WITHDRAW_FAILED`. |
## Pedido repetido [#pedido-repetido]
A `Idempotency-Key` tem de 1 a 255 caracteres ASCII visíveis, sem espaço. Vale por conta e não expira.
| Você manda | A API responde |
| ------------------------------------------------------ | ------------------------------------------------------------ |
| A mesma chave, com o mesmo `amount` e a mesma `pixKey` | O saque que já existe, no status atual. Nenhum Pix novo sai. |
| A mesma chave, com outro `amount` ou outra `pixKey` | `409` `WITHDRAW_IDEMPOTENCY_KEY_REUSED`. |
| Sem chave | Um saque novo a cada pedido. |
`comment` e `callbackUrl` não entram na comparação.
Num `502` com `PROVIDER_UNAVAILABLE`, ou `PROVIDER_REFUSED` com `details.status` `408` ou `429`, o Pix pode ter saído, e o valor fica fora do saldo disponível até o resultado ser conferido com o banco. Repita com a mesma `Idempotency-Key`, que devolve o saque original, ou procure o saque em [`GET /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/get_withdraws) antes de pedir de novo. Os demais `PROVIDER_REFUSED` são recusa definitiva: o valor volta na hora e o saque fica `FAILED`.
## Saldo e limites [#saldo-e-limites]
* Saldo insuficiente recusa o saque inteiro, sem saque parcial: `422` `WITHDRAW_INSUFFICIENT_BALANCE`, com `details.available` e `details.required`. `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE`: o banco não cobre o saque naquele momento, mesmo com `available` suficiente.
* O valor fica entre o mínimo e o máximo de saque da conta, em `withdraw` nos [limites](/docs/conta-digital/statement#limites).
* Há um teto diário para as saídas por Pix, somando saque e pagamento de Pix copia e cola. O teto e o quanto já foi usado no dia estão em `dailyWithdraw`; `0` bloqueia todo saque e `limit: null` é sem teto. Estourar responde `422` `WITHDRAW_DAILY_LIMIT`.
* Até 5 pedidos por minuto por credencial e 10 por conta, somados com pagamento de Pix copia e cola e estorno. Acima disso, a API responde `429` com `Retry-After`.
## Consultar e comprovar [#consultar-e-comprovar]
* **Listar:** [`GET /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/get_withdraws), escopo `WITHDRAW_READ`, paginada por cursor. Traz também os pagamentos de Pix copia e cola, com `operation: "EXTERNAL_PAYMENT"`.
* **Comprovante:** [`GET /transactions/withdraw/{withdrawId}/receipt`](/docs/conta-digital/endpoints/withdrawals/get_withdraw_receipt) devolve o PDF em base64, para saque `CONFIRMED`.
## Pix devolvido [#pix-devolvido]
Quando quem recebeu devolve o Pix, o valor volta ao saldo. Na maioria das vezes chega o webhook `WITHDRAW_REFUND_RECEIVED`, sem tarifa. Detalhes em [Pix recebido sem cobrança](/docs/conta-digital/deposits#devolução-de-um-pix-enviado).
As recusas, com o `code`, estão em [Sacar para chave Pix](/docs/conta-digital/endpoints/withdrawals/post_withdraw).