Saques Pix

Envie dinheiro da conta para uma chave Pix e saiba quando ele chegou ao destino.

POSTSacar para chave Pix/transactions/withdraw GETConsultar saque/transactions/withdraw/{withdrawId}Consultar destinatário

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

Opcional. Para mostrar o titular da chave antes de confirmar, use Consultar destinatário.

Pedir o saque

POST /transactions/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.

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

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. Todos os campos estão em Sacar para chave Pix.

Guardar o saque

A resposta (201) traz o saque. Guarde o id.

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

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}, 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	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

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 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 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.
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

Listar: GET /transactions/withdraw, 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 devolve o PDF em base64, para saque CONFIRMED.

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.

As recusas, com o code, estão em Sacar para chave Pix.

Saques Pix

Nesta página