Enviar um Pix para uma chave
Envie dinheiro da sua conta para uma chave Pix de qualquer instituição, informando o valor que o destino recebe e contando com a tarifa debitada além dele.
Envie o Pix
| Campo | Regra |
|---|---|
Idempotency-Key | Cabeçalho. Gere uma nova por saque e guarde-a com o pedido. |
amount | Valor em centavos. |
pixKey | Chave de destino. |
pixKeyType | Informe sempre que souber. Sem ele, a API deduz pelo formato, e uma chave de 11 dígitos pode ser lida como CPF ou como celular. |
comment | Opcional. |
Para mostrar o titular da chave antes de confirmar, veja Consultar o recebedor.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/withdraw' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--header 'Content-Type: application/json' \
--data '{
"amount": 10000,
"pixKey": "fulano@exemplo.com",
"pixKeyType": "EMAIL",
"comment": "Repasse semanal"
}'const idempotencyKey = crypto.randomUUID() // uma por saque; na retentativa, reenvie a mesma
const response = await fetch('https://api.sandbox.payzu.dev/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 withdraw = await response.json()
if (!response.ok) throw new Error(`${withdraw.code}: ${withdraw.message}`)
console.log(withdraw.id, withdraw.status, withdraw.totalDebited){
"id": "P20261005114011R4D8TN2WQZC127431",
"status": "PROCESSING",
"amount": 10000,
"serviceFee": 250,
"totalDebited": 10250,
"pixKey": "fulano@exemplo.com",
"bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999" },
"comment": "Repasse semanal",
"endToEndId": null,
"failureReason": null,
"callbackUrl": null,
"createdAt": "2026-10-05T14:40:11.002Z",
"confirmedAt": null
}Referência: Enviar um Pix para uma chave
Se a chamada falhar ou ficar sem resposta, repita com a mesma Idempotency-Key e os mesmos dados.
A rota retorna o saque existente, no estado em que estiver. Reaproveitar a mesma chave com outro valor ou destino dá 409. A cota é de 5 saques por minuto por credencial e 10 por conta, contando também pagamentos de copia e cola e devoluções.
Confirme a entrega
Dê o pagamento como feito só quando chegar WITHDRAW_COMPLETED.
| Aviso | Quando chega |
|---|---|
WITHDRAW_CREATED | A reserva saiu do saldo. |
WITHDRAW_COMPLETED | O dinheiro chegou. |
WITHDRAW_FAILED | O saque não saiu e a reserva voltou, com o motivo em reason. |
WITHDRAW_REFUND_RECEIVED | Quem recebeu devolveu o valor, inteiro ou em parte. Traz withdrawId e o depositId da entrada. |
Os corpos estão em Saque criado, Saque concluído, Saque falhou e Devolução de saque recebida. A consulta do saque serve para conciliar e para o caso de um aviso não chegar.
O saque não tem externalRef.
Guarde o id da resposta com o seu pedido para casar os avisos.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
WITHDRAW_INVALID_PIX_KEY | 400 | A chave PIX é inválida: CPF ou CNPJ com dígito verificador errado, ou 11 dígitos que não são CPF nem celular com DDD. |
WITHDRAW_PIX_KEY_TYPE_MISMATCH | 400 | O tipo informado não corresponde ao formato da chave PIX. |
WITHDRAW_DISABLED | 403 | Saque desabilitado para esta conta. |
WITHDRAW_ABOVE_TICKET_MAX | 422 | O valor excede o máximo permitido para saque. |
WITHDRAW_BELOW_TICKET_MIN | 422 | O valor é inferior ao mínimo permitido para saque. |
WITHDRAW_DAILY_LIMIT | 422 | O limite diário de saque desta conta foi atingido. |
WITHDRAW_INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para este saque. |
WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE | 422 | O saldo desta conta não cobre este saque agora. |
WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER | 422 | A chave PIX de destino foi recusada. |
WITHDRAW_UNRECOGNIZED_PIX_KEY | 422 | A chave PIX informada não corresponde a nenhum formato válido. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.