Introdução
Bem-vindo à documentação oficial da API Zypfy — um gateway de pagamentos server-to-server para merchants que precisam processar cobranças (cash-in) e saques (cash-out) com o mínimo de fricção e máxima confiabilidade. O PIX é o núcleo da plataforma — e, além dele, a Zypfy processa boleto, cartão, cobranças no México via SPEI (MXN) e saques em cripto.
Esta documentação foi escrita para desenvolvedores que vão integrar seus sistemas com a Zypfy. Nela você encontra:
- o fluxo completo de autenticação e cache de tokens;
- referência dos endpoints (com exemplos em cURL, Node.js, PHP e Python gerados automaticamente na sidebar direita);
- explicação detalhada de cada campo de request e response;
- tabela consolidada de códigos de erro e como remediar cada um;
- formato dos webhooks que a Zypfy envia ao seu servidor quando o status de uma transação muda;
- nuances operacionais críticas, como idempotência, IP whitelist, fallback de CPF inválido e comportamento do PIX Copia e Cola.
Visão geral
A Zypfy é uma ponte entre o seu sistema e os provedores PIX do mercado. Em vez de você integrar dezenas de adquirentes individualmente, você integra uma única API — a Zypfy cuida de rotear a transação pelo provedor ideal, consolidar os webhooks, calcular taxas, validar documentos, aplicar limites e expor tudo em um schema uniforme.
Cenários suportados:
| Cenário | Endpoint | Tempo típico |
|---|---|---|
| Cliente paga via PIX (QR Code ou Copia e Cola) | POST /api/payments/deposit | < 1s para gerar o QR |
| Cliente paga via boleto | POST /api/payments/deposit com paymentMethod=boleto | < 1s para emitir |
| Cliente paga via cartão | POST /api/payments/deposit com paymentMethod=card | Checkout seguro por link ou iframe; confirmação por webhook |
| Cliente no México paga via SPEI | POST /api/payments/mx/deposit | < 1s para gerar a CLABE |
| Merchant envia PIX para uma chave | POST /api/withdrawals/withdraw com key_type=CPF/CNPJ/EMAIL/PHONE/EVP | Instantâneo a poucos segundos |
| Merchant paga um QR Code de outro provedor | POST /api/withdrawals/withdraw com key_type=COPIAECOLA | Instantâneo (priority=HIGH) ou em fila (priority=NORM), janela de 10 min |
| Merchant envia saque em cripto | POST /api/withdrawals/crypto/withdraw | Depende da rede |
| Merchant converte saldo MXN em BRL | POST /api/accounts/mxn/convert | Imediato |
| Consulta status de uma transação | GET /api/transactions/deposit ou GET /api/transactions/withdraw | Imediato |
| Consulta saldo da carteira | GET /api/accounts/balance | Imediato |
URL base
Toda integração é feita contra:
https://api.zypfy.comNão existe sandbox separado — o ambiente é único (produção). Para testar fluxos sem risco, use valores mínimos (R$ 1,00) e seus próprios dados. Mais detalhes no guia Códigos de Erro sobre como simular falhas.
Formato das respostas
Todas as respostas são JSON UTF-8. Timestamps são retornados em ISO 8601 com timezone:
"created_at": "2026-04-18T12:00:00.000Z"O fuso horário canônico da Zypfy é America/Sao_Paulo (-03:00). Os timestamps em webhooks são no mesmo padrão.
Moedas
A moeda padrão da plataforma é o real (BRL) — é nela que ficam a carteira, os saques e as taxas.
A Zypfy também processa cobranças em peso mexicano (MXN) via SPEI. Esse saldo é separado do saldo em reais: fica em balance_mxn, e você o converte para BRL quando quiser sacar. Os webhooks trazem o campo currency ("BRL" ou "MXN") — use-o para rotear no seu backend, porque o mesmo endereço recebe os dois.
Detalhes do fluxo completo em Depósitos MXN (México).
Credenciais
Antes de qualquer chamada, gere suas credenciais no portal:
- Acesse https://app.zypfy.com/credentials.
- Conclua a verificação documental (KYC) da sua conta.
- Clique em Gerar credenciais. A Zypfy emite um
client_id+client_secret— guarde oclient_secretimediatamente porque ele só é exibido uma vez (na regeneração, o anterior é invalidado).
Ordem recomendada de leitura
- Autenticação — como pegar e cachear o JWT.
- Depósitos PIX — o principal fluxo de cash-in.
- Webhooks — como receber confirmações em tempo real.
- Verificando a assinatura dos webhooks — valide o HMAC antes de confiar.
- Saques PIX — cash-out por chave ou Copia e Cola.
- Consultas — reconciliação após falha de webhook.
- Saldo — consulta de carteira.
- Códigos de Erro — referência operacional.
Meios de pagamento e fluxos adicionais, conforme o que sua conta usar:
- Depósitos Boleto — cash-in por boleto.
- Depósitos Cartão — cash-in por cartão.
- Depósitos MXN (México) — cash-in via SPEI, saldo em pesos e conversão para BRL.
- Saques Cripto — cash-out em cripto.
- Disputas (MED) — contestações do PIX.
- Integração AdOptify — tracker de conversões.
Suporte
Dúvidas técnicas durante a integração? Fale com a equipe pelo canal de suporte do portal. Para reportar um problema de segurança, use [email protected] (PGP disponível sob solicitação).