Criar cobrança PIX (depósito)
https://api.zypfy.com/api/payments/depositCria 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
- Mínimo: definido em
min_deposit_amount(geralmente R$ 1,00); pode ser customizado por merchant. - Máximo por transação:
pix_in_limit_dailyconfigurável no dashboard — valores acima retornam HTTP 403.
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:
- dispara uma rajada de respostas de erro (ex.: repetir em loop uma
chamada que volta
4xx), ou - gera volume de requisições muito acima do padrão de uso normal.
Para nunca ser bloqueado:
- Cacheie o JWT (ver
/api/auth/login) — não faça login a cada requisição. - Não faça retry em loop de erros
4xx. Um422é erro permanente de payload (documento, e-mail, nome, telefone ou valor inválido): corrija o campo apontado no corpo do erro em vez de repetir a mesma requisição. - Para erros de rede ou
5xx, use backoff exponencial e retente com o mesmoexternal_id(idempotência) em vez de gerar um novo.
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
amountnumber (float)obrigatórioValor em BRL (ex.: 100.00).
exemplo:100mín. 0.01external_idstringobrigatórioSeu identificador único de pedido/cobrança. Serve como chave de idempotência — chamadas repetidas com o mesmo
external_idnão criam nova cobrança.exemplo:order-2026-0001clientCallbackUrlstring (uri) | nullURL HTTPS do seu webhook para este depósito. Se omitida, usa a URL configurada no portal para depósitos.
exemplo:https://minhaloja.com/webhooks/depositpayerobjectobrigatóriocampos de payer
namestringobrigatórioNome do pagador final (não do merchant).
exemplo:João Silvaemailstring (email)obrigatórioexemplo:[email protected]documentstringobrigatórioCPF (11 dígitos) ou CNPJ (14 dígitos) do pagador. Se inválido matematicamente, a Zypfy substitui internamente por um CPF válido de fallback para não bloquear a cobrança.
exemplo:12345678901phonestring | nullTelefone do pagador (opcional).
exemplo:11999999999
splitarray de objectArray opcional de destinos para repasse automático quando a cobrança for paga. Somente destino EMAIL.
campos de split
usernamestring (email)obrigatórioDestino do split — somente EMAIL é aceito.
exemplo:[email protected]percentageSplitstringobrigatórioPercentual do valor a repassar (em string).
exemplo:10
utm_sourcestring | nullLeadId do tracker (Xtracky etc.). Se a integração Xtracky estiver habilitada no portal, dispara os eventos
waiting_paymentepaid.exemplo:TT-1763007625226-yn4xita3qylwhutm_mediumstring | nullexemplo:cpcutm_campaignstring | nullexemplo:black_fridayutm_contentstring | nullexemplo:ad_variation_autm_termstring | nullexemplo:pix_checkoutplatformstring | nullLabel livre de plataforma de tracking. Default
ZYPFYquando encaminhado ao Xtracky.exemplo:ZYPFYsrcstring | nullParâmetro
srcextraído da URL do checkout. Repassado à Utmify emtrackingParameters.srcquando a integração estiver ativa.sckstring | nullParâmetro
sckextraído da URL do checkout. Repassado à Utmify emtrackingParameters.sckquando a integração estiver ativa.productsarray de objectLista opcional de produtos do pedido (usada pela Utmify). Se omitido, a Zypfy envia à Utmify um produto sintético com
name: "Depósito PIX",quantity: 1epriceInCents: amount*100.campos de products
idstringobrigatórioexemplo:SKU-123namestringobrigatórioexemplo:Camiseta BásicaplanIdstring | nullplanNamestring | nullquantityintegerobrigatórioexemplo:1mín. 1priceInCentsintegerobrigatórioPreço unitário em centavos.
exemplo:9990mín. 0
Respostas
200Idempotência: cobrança com este external_id já existia. O
registro existente foi devolvido (campo idempotent: true).
idintegerexemplo:101transaction_idstringexemplo:a1b2c3d4-e5f6-7890-abcd-ef1234567890external_idstringexemplo:order-2026-0001amountnumber (float)exemplo:100statusstringvalores:PENDINGCOMPLETEDFAILEDexemplo:PENDINGqrcodestring | nullidempotentbooleanexemplo:truemessagestringexemplo:Deposit already exists for this external_id.
201Cobrança criada com sucesso.
messagestringexemplo:Deposit created successfully.qrCodeResponseobjectcampos de qrCodeResponse
transactionIdstringID único da transação na Zypfy.
exemplo:a1b2c3d4-e5f6-7890-abcd-ef1234567890statusstringvalores:PENDINGCOMPLETEDFAILEDexemplo:PENDINGqrcodestringCódigo PIX Copia e Cola (BR Code EMV).
exemplo:00020126580014br.gov.bcb.pix...amountnumber (float)exemplo:100feenumber (float) | nullTaxa aplicada (pode estar ausente se ainda não calculada).
exemplo:2.5
400Campos obrigatórios ausentes, valor inválido ou abaixo do mínimo.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
401Não autenticado.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
403Valor acima do limite diário configurado para a conta.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
404Usuário não encontrado.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente 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.
codeINVALID_PAYER_DOCUMENTpayer.document.INVALID_PAYER_EMAILpayer.email (ex.: [email protected]).INVALID_PAYER_NAMEpayer.name.INVALID_PAYER_PHONEpayer.phone (DDD + número) ou omita o campo.INVALID_AMOUNTamount fora dos limites aceitos pelo provedoramount respeitando os limites do merchant.INVALID_PAYLOADmessagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente 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".
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.