ZypfyDocs Acessar painel
Guia de integração

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:

  1. 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.
  2. Seu saldo disponível cobre amount + fee. Consulte antes via GET /api/accounts/balance. Caso contrário: INSUFFICIENT_BALANCE.
  3. Seu token Bearer está válido. Veja Autenticação.

Endpoint

código
POST https://api.zypfy.com/api/withdrawals/withdraw

Headers: 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

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

json
{
  "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_typeFormato esperado em pix_keytaxId obrigatório?
CPF11 dígitos (só números)Não (derivado da chave)
CNPJ14 dígitos (só números)Não (derivado da chave)
EMAILEmail válido (normalizado para lowercase)Sim
PHONETelefone BR (normalizado para +55DDDNUMERO)Sim
EVPUUID v4 aleatórioSim

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)

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

CampoObrigatório?Notas
pix_keySimO EMV completo do QR (string começando com 00020101...). Não é uma chave PIX — é o código do QR.
amountSimDeve coincidir com o valor do QR Code. Se divergir, a transação é rejeitada.
taxIdOpcionalSe 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

json
{
  "message": "Withdrawal processed successfully.",
  "withdrawal": {
    "transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "PENDING",
    "amount": 50.00,
    "fee": 2.50,
    "total": 52.50
  }
}

Ciclo de vida (status)

código
                ┌────────────┐
                │  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_REFUNDED

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:

Qualquer um desses no body retorna:

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

json
"split": [
  { "username": "[email protected]", "percentageSplit": "10" }
]

O split é processado internamente quando o saque confirma. Destino sempre EMAIL.

Códigos de erro específicos

CódigoHTTPSignificadoRemediação
MISSING_RECEIVER_DOCUMENT400taxId ausente em saque EMAIL/PHONE/EVPIncluir taxId com CPF/CNPJ do recebedor.
DOCUMENT_MISMATCH400taxId diverge do beneficiário do QR (COPIAECOLA)Conferir CPF/CNPJ do destinatário original da cobrança.
QR_CODE_EXPIRED400QR Code passou da janela de 10 min ou é inválidoGerar/receber novo QR e tentar de novo.
INSUFFICIENT_BALANCE400Saldo menor que amount + feeConferir em /api/accounts/balance antes.
WITHDRAWAL_COOLDOWN429Gateway em cooldown após falha anteriorAguardar retry_after_seconds e retentar.
Unauthorized IP address.403IP não está na whitelistAdicionar IP em Credenciais → IPs autorizados.

Todos os códigos de erro, em detalhes, em Códigos de Erro.

Boas práticas

  1. Sempre chame GET /api/accounts/balance antes do saque — evita INSUFFICIENT_BALANCE.
  2. Derive external_id do ID do seu pedido — protege contra duplicatas em retentativas.
  3. Configure webhook de saque — é a fonte da verdade para status final. A resposta HTTP 200 do POST significa "aceito", não "confirmado".
  4. 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.