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
- O seu servidor cria a cobrança com
POST /api/payments/depositepaymentMethod: "card". - A resposta traz
checkoutUrl: a página segura de pagamento daquela cobrança. - Você mostra essa página ao comprador: dentro de um iframe na sua loja (recomendado) ou redirecionando/enviando o link.
- 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
POST https://api.zypfybr.com/api/payments/depositHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Body
{
"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
| Campo | Obrigatório | Descrição |
|---|---|---|
paymentMethod | Sim | Fixo em "card". |
amount | Sim | Valor em BRL. Mínimo R$ 5,00. |
external_id | Sim | Seu identificador único do pedido. |
payer.name | Sim | Nome do comprador. Vai pré-preenchido no campo "nome no cartão" (o comprador pode corrigir). |
payer.email | Sim | E-mail do comprador. |
payer.document | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos). |
payer.phone | Não | Telefone com DDD. |
clientCallbackUrl | Não | Webhook específico desta cobrança. |
split, utm_*, platform, src, sck, products | Não | Iguais 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
{
"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
}
}| Campo | Descrição |
|---|---|
status | Sempre PENDING na criação: ninguém pagou ainda. |
checkoutUrl | Página segura de pagamento desta cobrança. Use como veio. |
embedUrl | O mesmo endereço, nome explícito para uso em iframe. |
authenticationUrl / pendingAuthentication | Mantidos por compatibilidade com integrações antigas. Apontam para a mesma página. |
transactionId | Guarde 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.
<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:
- Mantenha
allow="payment". - Não use o atributo
sandbox. Se não puder remover, ele precisa incluir no mínimoallow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation. Sem isso a verificação do banco não abre. - Não esconda o overflow do container e não fixe uma altura pequena: o formulário cresce quando o banco pede confirmação. Use o evento
card.resize. - Se o seu site usa Content-Security-Policy, libere
https://pay.zypfybr.comemframe-src. - Se a sua página envia
Cross-Origin-Opener-Policy: same-origin, teste um pagamento completo no computador e no celular antes de publicar: a janela de verificação do banco pode perder o contato com o formulário.
Mensagens enviadas à sua página (postMessage):
type | Quando | Campos extras |
|---|---|---|
card.ready | Formulário carregado, pronto para receber o cartão. | — |
card.resize | A altura do conteúdo mudou. | height (px) |
card.paid | A Zypfy consultou a adquirente e confirmou o pagamento. | status: "paid" |
card.error | Recusa ou problema na tentativa. | code, terminal |
Todas trazem source: "zypfy" e transactionId.
Valores de code em card.error:
code | terminal | Significado |
|---|---|---|
declined | false | Cartão recusado. O comprador pode tentar de novo no mesmo formulário. |
token | false | Dados do cartão inválidos. Pode corrigir e tentar de novo. |
network | false | Falha de conexão do comprador. |
timeout | false | A confirmação está demorando. O resultado final chega pelo webhook. |
window_closed, canceled, popup_blocked | false | A verificação do banco foi fechada, cancelada ou bloqueada. Pode tentar de novo. |
attempts_exhausted | true | Acabaram as tentativas desta cobrança. |
closed, ended | true | A cobrança foi encerrada. |
expired | true | A cobrança passou da validade (24 horas). |
limit | true | O valor não é aceito no cartão. |
Com terminal: true, crie uma cobrança nova para o comprador tentar outra vez.
Opção 2 — link ou redirecionamento
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:
- libere o pedido pelo webhook, nunca só pelo evento da página;
- envie a conversão de campanha e o e-mail de confirmação pelo seu servidor, ao receber o webhook.
Exemplo do webhook de aprovação:
{
"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ção | status | O que fazer |
|---|---|---|
| Criada, aguardando o comprador | PENDING | Mostrar o checkout. Não liberar. |
| Comprador errou o cartão e ainda tem tentativas | PENDING | Nada: ele tenta de novo no mesmo formulário. |
| Paga e confirmada | COMPLETED | Liberar o pedido. |
- Recusa não gera webhook. A cobrança continua
PENDINGenquanto o comprador pode tentar de novo. - A cobrança vale 24 horas. Depois disso o formulário mostra "Este pagamento expirou" e é preciso criar outra.
- Não cancele o pedido por falta de webhook antes de 24 horas: um pagamento em análise antifraude pode ser confirmado minutos depois.
O que o comprador vê
- O formulário pede número do cartão, validade, CVV e nome impresso, e nada além disso.
- O formulário é da processadora e pode aparecer em inglês para compradores no Brasil.
- O banco do comprador pode pedir uma confirmação da compra (tela do banco dentro do formulário ou numa janela).
- Na fatura, a compra pode aparecer com um nome diferente do da sua loja. Avise o comprador perto do botão de pagar para evitar contestação por "não reconheço esta compra".
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):
- Aparece no saldo total e no extrato.
- Não entra no saldo disponível para saque até a data de liberação.
- Na data, a retenção cai automaticamente.
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
code | HTTP | Causa | O que fazer |
|---|---|---|---|
CARD_DISABLED | 403 | Cartão não habilitado nesta conta. | Solicitar liberação ao suporte. |
CARD_AMOUNT_TOO_LOW | 400 | Valor abaixo do mínimo (R$ 5,00). | Ajustar o valor. |
CARD_AMOUNT_TOO_HIGH | 400 | Valor acima do máximo por venda no cartão. A mensagem traz o máximo. | Dividir o pedido ou oferecer PIX. |
CARD_AMOUNT_INVALID | 400 | Valor não aceito no cartão. | Ajustar o valor ou oferecer PIX. |
CARD_TEMPORARILY_UNAVAILABLE | 503 | Cartão fora do ar no momento. | Tentar em alguns minutos ou oferecer PIX. |
INVALID_METHOD | 400 | paymentMethod fora de pix, boleto, card. | Corrigir o valor. |
DEPOSIT_DISABLED | 403 | Depósitos bloqueados na conta. | Falar com o suporte. |
Exemplo completo (Node.js)
// 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.