Saques PIX
Um saque é um envio de PIX do saldo do merchant para uma chave de destino ou para um código Copia e Cola. É o oposto do depósito.
Pré-requisitos
Antes do primeiro saque em produção, garanta que:
- Seu IP está na whitelist da conta. Saques só aceitam requisições vindas de IPs cadastrados em Credenciais → IPs autorizados no portal. Caso contrário:
HTTP 403 — Unauthorized IP address. - Seu saldo disponível cobre
amount + fee. Consulte antes viaGET /api/accounts/balance. Caso contrário:INSUFFICIENT_BALANCE. - Seu token Bearer está válido. Veja Autenticação.
Endpoint
POST https://api.zypfy.com/api/withdrawals/withdrawHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Duas modalidades
A Zypfy suporta dois tipos de saque:
A) Por chave PIX
Destino identificado por uma chave PIX cadastrada no SPI/DICT: CPF, CNPJ, email, telefone ou chave aleatória (EVP).
B) Por Copia e Cola (COPIAECOLA)
Destino é um BR Code EMV (o próprio QR Code / texto Copia e Cola). Útil para pagar cobranças dinâmicas geradas por outros provedores — pague boletos híbridos, faturas, e cobranças com valor fixo.
A) Saque por chave PIX
Exemplo CPF
{
"amount": 50.00,
"external_id": "saque-0001",
"pix_key": "12345678901",
"key_type": "CPF",
"name": "João Silva",
"description": "Pagamento pedido #100",
"clientCallbackUrl": "https://minhaloja.com/webhooks/withdrawal"
}Exemplo EMAIL (com taxId obrigatório)
{
"amount": 150.00,
"external_id": "saque-0002",
"pix_key": "[email protected]",
"key_type": "EMAIL",
"taxId": "12345678901",
"name": "João Silva"
}Tipos de chave aceitos
key_type | Formato esperado em pix_key | taxId obrigatório? |
|---|---|---|
CPF | 11 dígitos (só números) | Não (derivado da chave) |
CNPJ | 14 dígitos (só números) | Não (derivado da chave) |
EMAIL | Email válido (normalizado para lowercase) | Sim |
PHONE | Telefone BR (normalizado para +55DDDNUMERO) | Sim |
EVP | UUID v4 aleatório | Sim |
Para EMAIL, PHONE e EVP a própria chave não contém o CPF/CNPJ do recebedor — por isso o taxId é obrigatório. Se ausente, a API rejeita com MISSING_RECEIVER_DOCUMENT.
B) Saque por Copia e Cola (COPIAECOLA)
{
"amount": 25.00,
"external_id": "saque-0003",
"pix_key": "00020101021226790014br.gov.bcb.pix2557qr.exemplo.com/v2/abc123...",
"key_type": "COPIAECOLA",
"taxId": "12345678901",
"description": "Pagamento QR Code",
"clientCallbackUrl": "https://minhaloja.com/webhooks/withdrawal"
}Campos específicos de COPIAECOLA
| Campo | Obrigatório? | Notas |
|---|---|---|
pix_key | Sim | O EMV completo do QR (string começando com 00020101...). Não é uma chave PIX — é o código do QR. |
amount | Sim | Deve coincidir com o valor do QR Code. Se divergir, a transação é rejeitada. |
taxId | Opcional | Se fornecido, deve coincidir com o CPF/CNPJ do beneficiário original da cobrança. Se não bater: DOCUMENT_MISMATCH. |
Timeout de 10 minutos
QR Codes dinâmicos têm janela de 10 minutos para processamento. Se não for liquidado nesse prazo, a transação volta com QR_CODE_EXPIRED e o saldo é devolvido automaticamente.
Resposta 200 OK
{
"message": "Withdrawal processed successfully.",
"withdrawal": {
"transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"status": "PENDING",
"amount": 50.00,
"fee": 2.50,
"total": 52.50
}
}transaction_id— identificador único na Zypfy.status— estado inicial. Na maioria dos gateways, voltaPENDINGe confirma por webhook. Em gateways síncronos pode vir diretoCOMPLETED.total—amount + fee— valor efetivamente debitado da sua carteira.
Ciclo de vida (status)
┌────────────┐
│ PENDING │ ← resposta inicial (maioria dos gateways)
└─────┬──────┘
│
├───► (sucesso) ► COMPLETED ──► webhook enviado
│
├───► (fila) ► QUEUE ──► PENDING/COMPLETED/FAILED
│
└───► (falha) ► FAILED ──► webhook enviado, saldo devolvido
│
├───► (raro) REFUNDED
└───► (raro) PARTIALLY_REFUNDEDPENDING→ aceito, em processamento.QUEUE→ aguardando janela do provedor (congestionamento momentâneo).COMPLETED→ liquidado — saldo debitado, webhook enviado.FAILED→ rejeitado ou falhou — saldo devolvido automaticamente, webhook enviado comerror_code/error_message.REFUNDED/PARTIALLY_REFUNDED→ devolução (raro — apenas em contestações ou reversão bancária).
Idempotência
Igual ao depósito: external_id é chave de idempotência. Uma segunda chamada com o mesmo external_id retorna a mesma transação, nunca duplica o saque. Use isso para lidar com timeouts de rede no seu backend.
Campos NÃO aceitos no payload
A Zypfy rejeita (HTTP 400) se você enviar campos financeiros calculados pelo servidor. Nunca envie:
feetotalsplit_total/splitTotalsplit_pctfee_percent
Qualquer um desses no body retorna:
{
"message": "Campos não permitidos no payload: fee, total."
}Esta validação existe como defesa contra mass-assignment. fee e total são sempre calculados pela Zypfy com base nas taxas contratadas da sua conta.
Split em saques
Você pode fazer split no saque também:
"split": [
{ "username": "[email protected]", "percentageSplit": "10" }
]O split é processado internamente quando o saque confirma. Destino sempre EMAIL.
Códigos de erro específicos
| Código | HTTP | Significado | Remediação |
|---|---|---|---|
MISSING_RECEIVER_DOCUMENT | 400 | taxId ausente em saque EMAIL/PHONE/EVP | Incluir taxId com CPF/CNPJ do recebedor. |
DOCUMENT_MISMATCH | 400 | taxId diverge do beneficiário do QR (COPIAECOLA) | Conferir CPF/CNPJ do destinatário original da cobrança. |
QR_CODE_EXPIRED | 400 | QR Code passou da janela de 10 min ou é inválido | Gerar/receber novo QR e tentar de novo. |
INSUFFICIENT_BALANCE | 400 | Saldo menor que amount + fee | Conferir em /api/accounts/balance antes. |
WITHDRAWAL_COOLDOWN | 429 | Gateway em cooldown após falha anterior | Aguardar retry_after_seconds e retentar. |
Unauthorized IP address. | 403 | IP não está na whitelist | Adicionar IP em Credenciais → IPs autorizados. |
Todos os códigos de erro, em detalhes, em Códigos de Erro.
Boas práticas
- Sempre chame
GET /api/accounts/balanceantes do saque — evitaINSUFFICIENT_BALANCE. - Derive
external_iddo ID do seu pedido — protege contra duplicatas em retentativas. - Configure webhook de saque — é a fonte da verdade para status final. A resposta HTTP 200 do POST significa "aceito", não "confirmado".
- Se o webhook não chegar, reconcilie por polling via
GET /api/transactions/withdraw?external_id=seu_id. Não dependa de webhook 100% do tempo.