ZypfyDocs Acessar painel
Guia de integração

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:

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árioEndpointTempo típico
Cliente paga via PIX (QR Code ou Copia e Cola)POST /api/payments/deposit< 1s para gerar o QR
Cliente paga via boletoPOST /api/payments/deposit com paymentMethod=boleto< 1s para emitir
Cliente paga via cartãoPOST /api/payments/deposit com paymentMethod=cardCheckout seguro por link ou iframe; confirmação por webhook
Cliente no México paga via SPEIPOST /api/payments/mx/deposit< 1s para gerar a CLABE
Merchant envia PIX para uma chavePOST /api/withdrawals/withdraw com key_type=CPF/CNPJ/EMAIL/PHONE/EVPInstantâneo a poucos segundos
Merchant paga um QR Code de outro provedorPOST /api/withdrawals/withdraw com key_type=COPIAECOLAInstantâneo (priority=HIGH) ou em fila (priority=NORM), janela de 10 min
Merchant envia saque em criptoPOST /api/withdrawals/crypto/withdrawDepende da rede
Merchant converte saldo MXN em BRLPOST /api/accounts/mxn/convertImediato
Consulta status de uma transaçãoGET /api/transactions/deposit ou GET /api/transactions/withdrawImediato
Consulta saldo da carteiraGET /api/accounts/balanceImediato

URL base

Toda integração é feita contra:

código
https://api.zypfy.com

Nã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:

código
"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:

  1. Acesse https://app.zypfy.com/credentials.
  2. Conclua a verificação documental (KYC) da sua conta.
  3. Clique em Gerar credenciais. A Zypfy emite um client_id + client_secret — guarde o client_secret imediatamente porque ele só é exibido uma vez (na regeneração, o anterior é invalidado).

Ordem recomendada de leitura

  1. Autenticação — como pegar e cachear o JWT.
  2. Depósitos PIX — o principal fluxo de cash-in.
  3. Webhooks — como receber confirmações em tempo real.
  4. Verificando a assinatura dos webhooks — valide o HMAC antes de confiar.
  5. Saques PIX — cash-out por chave ou Copia e Cola.
  6. Consultas — reconciliação após falha de webhook.
  7. Saldo — consulta de carteira.
  8. Códigos de Erro — referência operacional.

Meios de pagamento e fluxos adicionais, conforme o que sua conta usar:

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