ZypfyDocs Acessar painel
Guia de integração

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

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

código
POST https://api.zypfy.com/api/payments/deposit

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

Body mínimo

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

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

CampoTipoDescrição
amountnumberValor em BRL (ex.: 100.00). Mínimo configurável (default R$ 1,00).
external_idstringSeu identificador único para esta cobrança. Serve como chave de idempotência (veja abaixo).
payer.namestringNome do pagador final (não o do merchant).
payer.emailstringEmail do pagador.
payer.documentstringCPF (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

CampoTipoDescrição
clientCallbackUrlstring (URL HTTPS)URL do webhook específica para esta cobrança. Se omitido, usa a URL configurada no portal.
payer.phonestringTelefone do pagador.
splitarrayArray de destinos EMAIL para repasse automático quando a cobrança for paga.
split[].usernamestring (email)Destino do split — somente EMAIL é aceito.
split[].percentageSplitstringPercentual do valor a repassar (ex.: "10" = 10%).
utm_sourcestring (máx 255)LeadId do tracker (Xtracky, etc.). Veja seção Xtracky abaixo.
utm_mediumstring (máx 64)Marketing medium (cpc, organic, etc.).
utm_campaignstring (máx 255)Nome da campanha.
utm_contentstring (máx 255)Identificador do criativo/variação.
utm_termstring (máx 255)Keyword/termo.
platformstring (máx 32)Label livre de tracking (default ZYPFY).

Resposta 201 Created (cobrança nova)

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

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:

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

Idempotência: boas práticas

  1. Nunca deixe a biblioteca HTTP gerar external_id aleatoriamente em cada tentativa. Derive do ID do seu pedido.
  2. Se precisar abrir uma nova cobrança para o mesmo pedido (porque a anterior expirou), use um novo external_id distinto (ex.: order-123-retry-2).
  3. A janela de idempotência vale enquanto a transação estiver PENDING ou COMPLETED. Se a anterior foi FAILED, 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:

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:

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

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:

  1. O campo utm_source está presente no body do depósito.
  2. A integração Xtracky está habilitada e configurada em Configurações → Xtracky no portal Zypfy.

Eventos disparados:

MomentoEvento Xtracky
Ao criar o depósito (QR gerado)waiting_payment
Ao confirmar o pagamentopaid

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

Códigos de erro

HTTPSituaçãoRemediação
400Campo obrigatório ausenteRevisar payload (amount, external_id, payer.*).
400Invalid amount.amount inválido ou ≤ 0.
400Depósito mínimo é R$ XEnviar valor ≥ mínimo configurado.
401Não autenticadoGerar novo token via /api/auth/login.
403Valor acima do limite por transaçãoConfigurar limite no dashboard ou fracionar.
404Usuário não encontradoCredenciais válidas mas conta inexistente/desabilitada.
500Erro interno / gateway indisponívelRetentar após alguns segundos.

Mais detalhes em Códigos de Erro.