ZypfyDocs Acessar painel
Depósitos PIX

Criar cobrança PIX (depósito)

POSThttps://api.zypfy.com/api/payments/deposit

Cria uma cobrança PIX e retorna o QR Code e o código Copia e Cola (qrcode) que você deve exibir ao pagador. Ao ser liquidada, a Zypfy dispara um webhook para a URL informada em clientCallbackUrl (ou para a URL configurada no portal, se nenhuma for enviada aqui).

Idempotência

external_id é a chave de idempotência. Se você chamar este endpoint duas vezes com o mesmo external_id enquanto a cobrança anterior estiver PENDING ou COMPLETED, você recebe a mesma transação (HTTP 200, com idempotent: true) em vez de uma nova. Use isso para lidar com retentativas em caso de timeout de rede no seu backend.

Limites

Limite de taxa (rate limit) e anti-abuso

Este endpoint não tem cota fixa de requisições: não existe um teto de "X chamadas por minuto" e ele nunca retorna 429. Ainda assim, uma proteção automática monitora cada IP de origem e pode bloqueá-lo temporariamente — a resposta nesse caso é um 403 da borda (Cloudflare), antes de chegar à API. Um IP é bloqueado quando:

Para nunca ser bloqueado:

Se seu IP for bloqueado apesar de uso legítimo, contate o suporte Zypfy informando o Cloudflare Ray ID da resposta 403 para liberação.

Payer: validação e fallback de documento

O campo payer.document aceita CPF (11 dígitos) ou CNPJ (14 dígitos). Se o documento enviado for matematicamente inválido, a Zypfy substitui por um CPF genérico válido internamente para não perder a venda (o pagador real continua pagando o QR code — o documento é usado apenas para o registro no BACEN/provedor). Garanta que payer.document, payer.name e payer.email reflitam o cliente final real quando possível.

Xtracky / UTMs (opcional)

Os campos utm_source, utm_medium, utm_campaign, utm_content, utm_term e platform são todos opcionais. Quando utm_source é enviado e a integração Xtracky está habilitada em "Configurações → Xtracky" no portal, a Zypfy dispara automaticamente eventos de conversão (waiting_payment ao gerar o PIX e paid ao confirmar o pagamento). A deduplicação é feita por orderId + utm_source no próprio Xtracky.

Utmify (opcional)

Os campos src, sck e products[] são opcionais e usados em conjunto com os UTMs acima. Quando a integração Utmify está habilitada em "Integrações → Utmify" no portal (com a credencial x-api-token configurada), a Zypfy dispara automaticamente pedidos para a Utmify (waiting_payment ao gerar o PIX e paid ao confirmar o pagamento). Se products[] não for enviado, a Zypfy cria um produto sintético (name: "Depósito PIX", quantity: 1, priceInCents: amount*100).

Split (opcional)

split[] aceita destinos do tipo EMAIL apenas no campo split[].username. O percentual vai em split[].percentageSplit (string). O valor dividido é creditado a cada destino quando a cobrança é confirmada.

Corpo da requisição

Respostas

200Idempotência: cobrança com este external_id já existia. O registro existente foi devolvido (campo idempotent: true).
  • idinteger
    exemplo: 101
  • transaction_idstring
    exemplo: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  • external_idstring
    exemplo: order-2026-0001
  • amountnumber (float)
    exemplo: 100
  • statusstring
    valores: PENDING COMPLETED FAILED
    exemplo: PENDING
  • qrcodestring | null
  • idempotentboolean
    exemplo: true
  • messagestring
    exemplo: Deposit already exists for this external_id.
201Cobrança criada com sucesso.
  • messagestring
    exemplo: Deposit created successfully.
  • qrCodeResponseobject
    campos de qrCodeResponse
    • transactionIdstring

      ID único da transação na Zypfy.

      exemplo: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    • statusstring
      valores: PENDING COMPLETED FAILED
      exemplo: PENDING
    • qrcodestring

      Código PIX Copia e Cola (BR Code EMV).

      exemplo: 00020126580014br.gov.bcb.pix...
    • amountnumber (float)
      exemplo: 100
    • feenumber (float) | null

      Taxa aplicada (pode estar ausente se ainda não calculada).

      exemplo: 2.5
400Campos obrigatórios ausentes, valor inválido ou abaixo do mínimo.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

401Não autenticado.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

403Valor acima do limite diário configurado para a conta.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

404Usuário não encontrado.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

422Dados do pagador inválidos. A cobrança não pôde ser criada porque algum campo enviado em payer (ou amount) foi rejeitado na validação. A resposta sempre traz um code estável que identifica qual campo corrigir — use o code para rotear no seu sistema; a message é texto pronto pra exibir ao cliente final.

code Quando ocorre Como corrigir
INVALID_PAYER_DOCUMENT CPF/CNPJ do pagador rejeitado Envie um CPF (11 dígitos) ou CNPJ (14 dígitos) válido em payer.document.
INVALID_PAYER_EMAIL E-mail do pagador inválido Envie um e-mail válido em payer.email (ex.: [email protected]).
INVALID_PAYER_NAME Nome do pagador inválido/curto/ausente Envie o nome completo do pagador em payer.name.
INVALID_PAYER_PHONE Telefone do pagador inválido Envie um telefone válido em payer.phone (DDD + número) ou omita o campo.
INVALID_AMOUNT amount fora dos limites aceitos pelo provedor Ajuste amount respeitando os limites do merchant.
INVALID_PAYLOAD Outro campo do payload foi rejeitado, mas não conseguimos identificar qual Revise nome, e-mail, CPF/CNPJ e valor enviados.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

500Erro interno: provedor indisponível, timeout ou gateway não configurado. Não é problema do payload do lojista — é seguro tentar novamente em alguns segundos. Sempre vem com code: "PROVIDER_UNAVAILABLE".
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.