Depósitos PIX
Um depósito é uma cobrança PIX — você gera um QR Code (e o respectivo código Copia e Cola) para o seu cliente pagar. Quando o PIX cai, a Zypfy notifica seu servidor por webhook.
Fluxo completo
┌──────────┐ 1. POST /api/payments/deposit ┌──────────┐
│ Seu │ ───────────────────────────────────▶│ Zypfy │
│ backend │ │ │
└────┬─────┘◀── 2. { qrcode, transactionId } ────┴─────┬────┘
│ │
│ 3. Exibe QR Code / Copia e Cola ao pagador │
▼ │
┌──────────┐ │
│ Cliente │ │
│ final │ │
└────┬─────┘ │
│ 4. Paga o PIX │
▼ │
┌──────────────────────────────────────────────────────┴─────┐
│ Sistema PIX (BACEN + provedor) │
└──────────────────────────────────────────────────────┬─────┘
│
┌────────────────────────────────────────────────┘
│ 5. Webhook: type=Deposit, status=COMPLETED
▼
┌──────────┐
│ Seu │
│ backend │ ── 6. Confirma o pedido no seu sistema
└──────────┘Endpoint
POST https://api.zypfy.com/api/payments/depositHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Body mínimo
{
"amount": 100.00,
"external_id": "order-2026-0001",
"clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
"payer": {
"name": "João Silva",
"email": "[email protected]",
"document": "12345678901"
}
}Body completo (com Split e UTMs)
{
"amount": 250.00,
"external_id": "order-2026-0042",
"clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
"payer": {
"name": "Maria Souza",
"email": "[email protected]",
"document": "98765432100",
"phone": "11987654321"
},
"split": [
{ "username": "[email protected]", "percentageSplit": "10" },
{ "username": "[email protected]", "percentageSplit": "5" }
],
"utm_source": "TT-1763007625226-yn4xita3qylwh",
"utm_medium": "cpc",
"utm_campaign": "black_friday",
"utm_content": "ad_variation_a",
"utm_term": "pix_checkout",
"platform": "ZYPFY"
}Campos
Obrigatórios
| Campo | Tipo | Descrição |
|---|---|---|
amount | number | Valor em BRL (ex.: 100.00). Mínimo configurável (default R$ 1,00). |
external_id | string | Seu identificador único para esta cobrança. Serve como chave de idempotência (veja abaixo). |
payer.name | string | Nome do pagador final (não o do merchant). |
payer.email | string | Email do pagador. |
payer.document | string | CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador. Se inválido, a Zypfy aplica um CPF de fallback internamente (ver seção abaixo). |
Opcionais
| Campo | Tipo | Descrição |
|---|---|---|
clientCallbackUrl | string (URL HTTPS) | URL do webhook específica para esta cobrança. Se omitido, usa a URL configurada no portal. |
payer.phone | string | Telefone do pagador. |
split | array | Array de destinos EMAIL para repasse automático quando a cobrança for paga. |
split[].username | string (email) | Destino do split — somente EMAIL é aceito. |
split[].percentageSplit | string | Percentual do valor a repassar (ex.: "10" = 10%). |
utm_source | string (máx 255) | LeadId do tracker (Xtracky, etc.). Veja seção Xtracky abaixo. |
utm_medium | string (máx 64) | Marketing medium (cpc, organic, etc.). |
utm_campaign | string (máx 255) | Nome da campanha. |
utm_content | string (máx 255) | Identificador do criativo/variação. |
utm_term | string (máx 255) | Keyword/termo. |
platform | string (máx 32) | Label livre de tracking (default ZYPFY). |
Resposta 201 Created (cobrança nova)
{
"message": "Deposit created successfully.",
"qrCodeResponse": {
"transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "PENDING",
"qrcode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef12345678905204000053039865406100.005802BR5913JOAO DA SILVA6008SAO PAULO62070503***6304ABCD",
"amount": 100.00,
"fee": 2.50
}
}transactionId— identificador único da transação na Zypfy. Guarde como referência.qrcode— código PIX Copia e Cola completo (BR Code EMV). Exiba-o como texto selecionável e gere o QR Code a partir dele com qualquer lib de QR (ex.:qrcodeno Node,endroid/qr-codeno PHP). Não use um campo "qrcodeBase64" — a Zypfy retorna o EMV de onde você mesmo pode gerar a imagem.amount— valor em BRL.fee— taxa aplicada (pode estar ausente em alguns gateways).
Resposta 200 OK (idempotência — cobrança já existia)
Se você chamar este endpoint duas vezes com o mesmo external_id enquanto a cobrança anterior ainda está PENDING ou COMPLETED, a Zypfy não cria outra — devolve a existente com idempotent: true:
{
"id": 101,
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"external_id": "order-2026-0001",
"amount": 100.00,
"status": "PENDING",
"qrcode": "00020126580014br.gov.bcb.pix...",
"idempotent": true,
"message": "Deposit already exists for this external_id."
}Como isso protege seu backend
- Se houver timeout de rede na primeira chamada, basta repetir com o mesmo
external_id— você recebe a mesma cobrança original sem duplicar. - Se você gerar o
external_ida partir do ID do seu pedido (ex.:order-${pedido_id}), retentativas são sempre seguras.
Idempotência: boas práticas
- Nunca deixe a biblioteca HTTP gerar
external_idaleatoriamente em cada tentativa. Derive do ID do seu pedido. - Se precisar abrir uma nova cobrança para o mesmo pedido (porque a anterior expirou), use um novo
external_iddistinto (ex.:order-123-retry-2). - A janela de idempotência vale enquanto a transação estiver
PENDINGouCOMPLETED. Se a anterior foiFAILED, uma nova chamada cria um novo registro.
Payer: validação e fallback de documento
O payer.document aceita CPF (11 dígitos) ou CNPJ (14 dígitos). A Zypfy valida o dígito verificador. Se o documento for:
- válido matematicamente → é usado como está (registro BACEN preserva CPF real do pagador);
- inválido ou em blacklist interna → a Zypfy substitui internamente por um CPF genérico válido para não bloquear a venda (o pagador real continua pagando normalmente o QR).
O mesmo se aplica a payer.name e payer.email: se ausentes, a Zypfy preenche com valores genéricos (Pagamento Digital, [email protected]). Envie os reais sempre que possível para melhor experiência do pagador (o QR Code PIX mostra o nome do pagador esperado em alguns bancos).
Split de pagamento
Se sua conta tiver a feature habilitada, você pode dividir o valor recebido entre múltiplos destinos no momento do pagamento:
"split": [
{ "username": "[email protected]", "percentageSplit": "10" },
{ "username": "[email protected]", "percentageSplit": "5" }
]- Somente
usernamedo tipo EMAIL é aceito — não é possível split para CPF/CNPJ. - O percentual vai em string (
"10"= 10%,"2.5"= 2,5%). - O split é processado internamente quando a cobrança confirma.
Integração com Xtracky (opcional)
Se você usa Xtracky para attribuition de campanhas, a Zypfy dispara eventos de conversão automaticamente quando três condições são atendidas:
- O campo
utm_sourceestá presente no body do depósito. - A integração Xtracky está habilitada e configurada em Configurações → Xtracky no portal Zypfy.
Eventos disparados:
| Momento | Evento Xtracky |
|---|---|
| Ao criar o depósito (QR gerado) | waiting_payment |
| Ao confirmar o pagamento | paid |
A deduplicação é feita pelo próprio Xtracky via orderId + utm_source. Formato recomendado do utm_source: <plataforma>-<timestamp>-<random> (ex.: TT-1763007625226-yn4xita3qylwh onde TT = TikTok, FB = Facebook, KW = Kwai, GG = Google).
Limites
- Mínimo por transação: definido em
min_deposit_amount(default R$ 1,00) — customizável por merchant. - Máximo por transação: definido em
pix_in_limit_dailyno dashboard. Acima: HTTP 403 commessage: "Limite de PIX IN por transação é R$ X"e campolimitna resposta.
Códigos de erro
| HTTP | Situação | Remediação |
|---|---|---|
| 400 | Campo obrigatório ausente | Revisar payload (amount, external_id, payer.*). |
| 400 | Invalid amount. | amount inválido ou ≤ 0. |
| 400 | Depósito mínimo é R$ X | Enviar valor ≥ mínimo configurado. |
| 401 | Não autenticado | Gerar novo token via /api/auth/login. |
| 403 | Valor acima do limite por transação | Configurar limite no dashboard ou fracionar. |
| 404 | Usuário não encontrado | Credenciais válidas mas conta inexistente/desabilitada. |
| 500 | Erro interno / gateway indisponível | Retentar após alguns segundos. |
Mais detalhes em Códigos de Erro.