ZypfyDocs Acessar painel
Guia de integração

Depósitos Cartão

Cartão de crédito com checkout seguro hospedado pela Zypfy: abra como link ou coloque num iframe. Seu servidor nunca toca no cartão.

Depósitos Cartão de Crédito

A Zypfy recebe cartão de crédito pela mesma rota de depósito, com paymentMethod: "card". O comprador digita o cartão num formulário seguro hospedado pela Zypfy, que você abre como link ou coloca dentro da sua página com um iframe. O seu servidor nunca recebe nem envia número de cartão, validade ou CVV.

Como funciona

  1. O seu servidor cria a cobrança com POST /api/payments/deposit e paymentMethod: "card".
  2. A resposta traz checkoutUrl: a página segura de pagamento daquela cobrança.
  3. Você mostra essa página ao comprador: dentro de um iframe na sua loja (recomendado) ou redirecionando/enviando o link.
  4. O comprador paga. A Zypfy confirma com a adquirente e envia o webhook com status: "COMPLETED". Libere o pedido só nesse momento.

Como os dados do cartão são digitados no formulário seguro, a sua aplicação não entra no escopo do PCI-DSS por causa desta integração.

Endpoint

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

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

Body

json
{
  "paymentMethod": "card",
  "amount": 250.00,
  "external_id": "order-2026-0042",
  "clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
  "payer": {
    "name": "Maria Souza",
    "email": "[email protected]",
    "document": "98765432100",
    "phone": "11999998888"
  }
}

Campos

CampoObrigatórioDescrição
paymentMethodSimFixo em "card".
amountSimValor em BRL. Mínimo R$ 5,00.
external_idSimSeu identificador único do pedido.
payer.nameSimNome do comprador. Vai pré-preenchido no campo "nome no cartão" (o comprador pode corrigir).
payer.emailSimE-mail do comprador.
payer.documentSimCPF (11 dígitos) ou CNPJ (14 dígitos).
payer.phoneNãoTelefone com DDD.
clientCallbackUrlNãoWebhook específico desta cobrança.
split, utm_*, platform, src, sck, productsNãoIguais ao PIX. Veja Depósitos PIX.

Não envie dados de cartão. Se o objeto card vier no body, ele é descartado.

Parcelamento: o checkout cobra à vista (1x). Não há escolha de parcelas no formulário.

Resposta — 201 Created

json
{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "154867b5-a715-4776-8140-bb42510fcc2d",
    "status": "PENDING",
    "qrcode": null,
    "amount": 250.00,
    "paymentMethod": "card",
    "card": null,
    "hostedCheckout": true,
    "checkoutUrl": "https://pay.zypfybr.com/cartao/154867b5-a715-4776-8140-bb42510fcc2d",
    "embedUrl": "https://pay.zypfybr.com/cartao/154867b5-a715-4776-8140-bb42510fcc2d",
    "authenticationUrl": "https://pay.zypfybr.com/cartao/154867b5-a715-4776-8140-bb42510fcc2d",
    "pendingAuthentication": true,
    "fee": 20.48
  }
}
CampoDescrição
statusSempre PENDING na criação: ninguém pagou ainda.
checkoutUrlPágina segura de pagamento desta cobrança. Use como veio.
embedUrlO mesmo endereço, nome explícito para uso em iframe.
authenticationUrl / pendingAuthenticationMantidos por compatibilidade com integrações antigas. Apontam para a mesma página.
transactionIdGuarde junto do pedido. É o identificador da cobrança nas consultas e no webhook.

Mostrar o pagamento ao comprador

Opção 1 — iframe na sua página (recomendado)

O comprador paga sem sair da sua loja.

html
<iframe
  id="zypfy-cartao"
  src="CHECKOUT_URL_DA_RESPOSTA"
  allow="payment"
  style="width:100%; max-width:520px; border:0; min-height:460px"></iframe>

<script>
  window.addEventListener('message', function (e) {
    if (e.origin !== 'https://pay.zypfybr.com') return;
    var d = e.data || {};
    if (d.source !== 'zypfy') return;

    if (d.type === 'card.resize') {
      // Ajuste a altura do iframe ao conteúdo.
      document.getElementById('zypfy-cartao').style.height = d.height + 'px';
    }
    if (d.type === 'card.paid') {
      // Pagamento confirmado pela Zypfy. Mostre a tela de "obrigado".
      // A liberação do pedido continua sendo pelo webhook (veja abaixo).
    }
    if (d.type === 'card.error' && d.terminal) {
      // Cobrança encerrada (tentativas esgotadas, expirada etc.).
      // Para tentar de novo, crie uma cobrança nova.
    }
  });
</script>

Requisitos do iframe:

Mensagens enviadas à sua página (postMessage):

typeQuandoCampos extras
card.readyFormulário carregado, pronto para receber o cartão.—
card.resizeA altura do conteúdo mudou.height (px)
card.paidA Zypfy consultou a adquirente e confirmou o pagamento.status: "paid"
card.errorRecusa ou problema na tentativa.code, terminal

Todas trazem source: "zypfy" e transactionId.

Valores de code em card.error:

codeterminalSignificado
declinedfalseCartão recusado. O comprador pode tentar de novo no mesmo formulário.
tokenfalseDados do cartão inválidos. Pode corrigir e tentar de novo.
networkfalseFalha de conexão do comprador.
timeoutfalseA confirmação está demorando. O resultado final chega pelo webhook.
window_closed, canceled, popup_blockedfalseA verificação do banco foi fechada, cancelada ou bloqueada. Pode tentar de novo.
attempts_exhaustedtrueAcabaram as tentativas desta cobrança.
closed, endedtrueA cobrança foi encerrada.
expiredtrueA cobrança passou da validade (24 horas).
limittrueO valor não é aceito no cartão.

Com terminal: true, crie uma cobrança nova para o comprador tentar outra vez.

Abra checkoutUrl na mesma aba, numa aba nova ou envie o link ao comprador (WhatsApp, e-mail). A página mostra o valor, o formulário e a confirmação "Pagamento aprovado" quando a Zypfy confirmar.

Confirmação do pagamento

O que vale para liberar o pedido é o webhook com status: "COMPLETED" (ou a consulta GET /api/transactions/deposit?external_id=... com esse status). O evento card.paid da página serve para a tela, não para liberar o pedido: o comprador pode fechar a aba antes, e em alguns navegadores de aplicativo (Instagram, Facebook) o pagamento termina numa página do banco e o evento não chega à sua loja.

Por isso:

Exemplo do webhook de aprovação:

json
{
  "type": "Deposit",
  "external_id": "order-2026-0042",
  "transaction_id": "154867b5-a715-4776-8140-bb42510fcc2d",
  "status": "COMPLETED",
  "amount": 250.00,
  "fee": 20.48,
  "payment_method": "card",
  "updated_at": "2026-10-15T13:40:12.000Z"
}

Valide a assinatura como em Verificando a assinatura dos webhooks.

Ciclo da cobrança

SituaçãostatusO que fazer
Criada, aguardando o compradorPENDINGMostrar o checkout. Não liberar.
Comprador errou o cartão e ainda tem tentativasPENDINGNada: ele tenta de novo no mesmo formulário.
Paga e confirmadaCOMPLETEDLiberar o pedido.

O que o comprador vê

Liquidação: retenção D+N

O valor entra no seu saldo na aprovação, mas fica retido até a data de liberação da sua conta (D+N, configurável pelo suporte):

Consulte /api/accounts/balance para ver saldo total e disponível.

Chargeback

O titular pode contestar a compra por meses. Um chargeback reverte a venda e debita o valor do seu saldo. Guarde o transactionId e as evidências da entrega (nota, rastreio, aceite de termos, logs de acesso).

Erros

codeHTTPCausaO que fazer
CARD_DISABLED403Cartão não habilitado nesta conta.Solicitar liberação ao suporte.
CARD_AMOUNT_TOO_LOW400Valor abaixo do mínimo (R$ 5,00).Ajustar o valor.
CARD_AMOUNT_TOO_HIGH400Valor acima do máximo por venda no cartão. A mensagem traz o máximo.Dividir o pedido ou oferecer PIX.
CARD_AMOUNT_INVALID400Valor não aceito no cartão.Ajustar o valor ou oferecer PIX.
CARD_TEMPORARILY_UNAVAILABLE503Cartão fora do ar no momento.Tentar em alguns minutos ou oferecer PIX.
INVALID_METHOD400paymentMethod fora de pix, boleto, card.Corrigir o valor.
DEPOSIT_DISABLED403Depósitos bloqueados na conta.Falar com o suporte.

Exemplo completo (Node.js)

javascript
// 1) Servidor: cria a cobrança e devolve só a URL do checkout para o front.
app.post('/checkout/cartao', async (req, res) => {
  const pedido = await criarPedido(req.body);

  const { data } = await axios.post(
    'https://api.zypfybr.com/api/payments/deposit',
    {
      paymentMethod: 'card',
      amount: pedido.total,
      external_id: pedido.id,
      clientCallbackUrl: 'https://minhaloja.com/webhooks/deposit',
      payer: {
        name: pedido.cliente.nome,
        email: pedido.cliente.email,
        document: pedido.cliente.cpf,
      },
    },
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const r = data.qrCodeResponse;
  await db.pedidos.update(
    { gateway_id: r.transactionId, status: 'AGUARDANDO' },
    { where: { id: pedido.id } }
  );
  res.json({ checkoutUrl: r.checkoutUrl });
});

// 2) Webhook: única fonte de verdade para liberar o pedido.
app.post('/webhooks/deposit', async (req, res) => {
  // valide a assinatura antes de confiar no corpo
  const ev = req.body;
  if (ev.type === 'Deposit' && ev.payment_method === 'card' && ev.status === 'COMPLETED') {
    await liberarPedido(ev.external_id);
  }
  res.sendStatus(200);
});

No front, coloque checkoutUrl no src do iframe, como na Opção 1.