ZypfyDocs Acessar painel
Guia de integração

Cartões virtuais

Os cartões virtuais Zypfy são pré-pagos e controlados por limite. Você emite o cartão uma vez e adiciona somente o valor que pretende gastar. A Zypfy aumenta o limite junto à adquirente GGPix e debita a carga da sua carteira.

Antes de começar

Tarifas

Consulte sempre GET /api/v1/cards/fees antes de mostrar uma simulação ao usuário. São três momentos de cobrança, todos debitados da carteira Zypfy — nunca do saldo do cartão:

As tarifas podem ser personalizadas por merchant. Quando não existe um override específico de cartão, a carga herda o percentual e o piso da sua taxa PIX Out; a compra não herda nada — ou é a tarifa global, ou o override da conta. Por isso, não fixe esses valores no seu código: use a resposta de /fees.

Exemplo para uma carga de R$ 100,00 com load.percent = 0.03 e load.minimumCents = 90: amountCents=10000, feeCents=300 e totalDebitedCents=10300.

No extrato, o que cada linha custou à conta está em accountDebitCents, e a tarifa Zypfy daquele lançamento, em feeCents.

Fluxo recomendado

  1. Consulte as tarifas.
  2. Emita o cartão com POST /api/v1/cards.
  3. Revele PAN/CVV somente quando o portador solicitar.
  4. Carregue o cartão com POST /api/v1/cards/{cardId}/load.
  5. Cadastre um destino de webhook (POST /api/v1/cards/webhooks) para receber compra, recusa e estorno na hora.
  6. Acompanhe compras em GET /api/v1/cards/{cardId}/transactions ou no histórico global — o extrato continua sendo a fonte de verdade e a rede de segurança.
  7. Bloqueie temporariamente quando necessário; cancele somente de forma definitiva.

Emissão

bash
curl --request POST 'https://api.zypfy.com/api/v1/cards' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Idempotency-Key: card-order-2026-0001' \
  --header 'Content-Type: application/json' \
  --data '{
    "holderName": "João da Silva",
    "nickname": "Marketing",
    "singleUse": false,
    "initialLoadCents": 25000,
    "webhookUrl": "https://seusistema.com/webhooks/cartao"
  }'

initialLoadCents é opcional. Se você preferir separar a emissão da carga, omita o campo e use o endpoint /load em seguida.

webhookUrl também é opcional: quando informado, o destino de webhook daquele cartão nasce junto com ele e a resposta traz o secret da assinatura.

Adicionar limite

bash
curl --request POST 'https://api.zypfy.com/api/v1/cards/CARD_ID/load' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Idempotency-Key: card-load-2026-0001' \
  --header 'Content-Type: application/json' \
  --data '{ "amountCents": 10000 }'

A resposta informa loadedCents, feeCents e totalDebitedCents. Uma resposta HTTP 202 significa que a operação foi aceita e está em conciliação segura; não gere uma nova chave. Consulte novamente usando a mesma chave/requisição.

Idempotência e retentativas

Envie Idempotency-Key na emissão e em toda carga. A chave deve ter entre 8 e 100 caracteres (A-Z, a-z, 0-9, ponto, sublinhado, dois-pontos ou hífen). Se houver timeout, repita exatamente a mesma operação com a mesma chave. Nunca troque a chave enquanto o resultado da tentativa anterior for incerto.

Dados sensíveis

GET /api/v1/cards/{cardId}/sensitive retorna PAN e CVV e usa Cache-Control: no-store. Esses campos devem existir somente na memória e na tela durante o tempo estritamente necessário.

Não salve nem envie PAN/CVV para:

A dashboard Zypfy oculta os dados automaticamente após 60 segundos.

O extrato do cartão

GET /api/v1/cards/{cardId}/transactions traz o extrato de um cartão; GET /api/v1/cards/transactions, o de todos os cartões da conta (aceita startDate e endDate). Ambos aceitam page e limit (máx. 200) e vêm ordenados do lançamento mais recente para o mais antigo.

O extrato é a vida inteira do cartão: a emissão, cada carga, as compras aprovadas e as recusadas, estornos, liquidações, verificações e os tributos da compra internacional. O que muda de uma linha para outra é apenas de qual saldo ela tirou dinheiro, e isso vem explícito em cada lançamento.

Quatro cuidados ao consumir:

1. Some por affectsBalance + direction, nunca por type. Só as linhas com affectsBalance: true movem o saldo do cartão: CREDIT soma, DEBIT subtrai. Ficam de fora a verificação (vale R$ 0,00), a liquidação (repetição de uma compra já listada), a emissão e tudo que foi recusado. Lista fixa de tipos quebra quando um tipo novo aparece; esses dois campos, não.

2. A tarifa Zypfy não sai do cartão. Ela é debitada do saldo da sua carteira — é o que diz feeChargedFrom: "ACCOUNT_BALANCE". Quanto cada linha custou à conta está em accountDebitCents: somando essa coluna você tem o custo total do cartão, sem contar nada duas vezes.

3. Uma linha muda depois de criada. Uma compra liquida, estorna ou é revertida, e o id continua o mesmo. Reconcilie por updatedAt, não só por occurredAt. Não altere uma compra antiga para representar um estorno: o estorno é uma linha própria, com type: REFUND.

4. ISSUER_FEE não é cobrança nossa. São o IOF e o spread cambial de uma compra internacional do próprio portador, identificados pelo nome do tributo em merchantName. A compra que os gerou vem em relatedTo.

Tipos hoje: ISSUE, LOAD, PURCHASE, REFUND, VERIFICATION, SETTLEMENT e ISSUER_FEE — trate a lista como aberta.

Webhook de cartão

Em vez de consultar o extrato de tempos em tempos, receba o evento na hora. Cadastre uma ou mais URLs e a Zypfy avisa a cada compra, recusa, carga, estorno ou mudança de status. O polling continua funcionando e continua sendo a rede de segurança — o webhook é o atalho.

código
POST   /api/v1/cards/webhooks              cadastra um destino
GET    /api/v1/cards/webhooks              lista, com a saúde de cada um
PATCH  /api/v1/cards/webhooks/{id}         liga/desliga, troca url ou eventos
DELETE /api/v1/cards/webhooks/{id}         remove

Cadastrar

bash
curl --request POST 'https://api.zypfy.com/api/v1/cards/webhooks' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://seusistema.com/webhooks/cartao",
    "label": "producao"
  }'

A resposta traz um secret — guarde: ele aparece uma única vez. É com ele que você confere a assinatura de cada entrega. Perdeu? Apague o destino e cadastre outro.

Regras da URL: https obrigatório, host público (endereço interno é recusado), portas 443 ou 8443. Até 20 destinos por conta.

Vários destinos

Cadastre quantos quiser — todos recebem. Cada destino pode ser da conta inteira (padrão) ou de um cartão só, passando cardId: é o caso de quem emite um cartão por cliente e quer o evento no sistema daquele cliente. Se a mesma URL casar pelos dois caminhos, ela recebe uma vez só.

Atalho: mandando webhookUrl no corpo do POST /api/v1/cards, o destino daquele cartão já nasce junto com ele — e a resposta da emissão traz o secret. Assim você não perde nem o card.issued.

Por padrão o destino recebe todos os eventos. Para filtrar, mande events com a lista desejada — evento desconhecido é recusado na hora do cadastro, para um erro de digitação não virar "meu webhook não chega".

Eventos

eventQuando dispara
card.issuedCartão emitido
card.load.completedCarga concluída — o saldo já está no cartão
card.load.failedCarga não se concretizou; o valor voltou para o seu saldo
card.purchase.approvedCompra aprovada
card.purchase.declinedCompra recusada. Evento próprio: você não precisa inspecionar o corpo para saber se deve agir
card.purchase.updatedA rede reprocessou um lançamento que você já recebeu (liquidou, estornou, mudou de valor). O transaction.id é o mesmo — atualize, não crie outro
card.refundEstorno da loja creditado no cartão — dinheiro de volta, entra no saldo
card.reversalAutorização cancelada: o valor nunca saiu do cartão. Não é estorno da loja — se você reservou o valor na compra, libere a reserva em vez de creditar
card.settlementLiquidação de uma compra já avisada. Mesmo dinheiro — não debite de novo
card.verificationChecagem de R$ 0,00 (cadastro em carteira digital, cartão on-file)
card.issuer_feeIOF ou spread de compra internacional
card.status_changedCartão bloqueado, desbloqueado ou cancelado

O corpo

O campo transaction é exatamente a mesma linha que o extrato devolveria para aquele lançamento — mesmos campos, mesmo significado, incluindo affectsBalance, direction e accountDebitCents. Quem já lê o extrato não aprende formato novo. Em card.status_changed ele vem null: não há dinheiro envolvido.

json
{
  "id": "0e542b1c-2303-4870-a192-f5e60903b025",
  "event": "card.purchase.approved",
  "sentAt": "2026-08-11T16:45:40.407Z",
  "card": {
    "id": "7d219916-2c09-4028-b93a-e165710cee2a",
    "last4": "5792",
    "nickname": "Anuncios",
    "status": "ACTIVE"
  },
  "transaction": {
    "id": "1f0c8a2e-5b41-4a77-9a1e-0f2b6c3d4e5f",
    "type": "PURCHASE",
    "status": "COMPLETE",
    "direction": "DEBIT",
    "affectsBalance": true,
    "amountCents": 3135,
    "accountDebitCents": 80,
    "feeCents": 80,
    "feeChargedFrom": "ACCOUNT_BALANCE",
    "merchantName": "DramaBox_A U243550519",
    "occurredAt": "2026-08-09T23:09:28.609Z"
  }
}

Conferindo a assinatura

Toda entrega leva o cabeçalho X-Webhook-Signature no formato t=<epoch>,v1=<hmac>. O HMAC é SHA-256 de <t>.<corpo cru> com o secret daquele destino. O número da tentativa vem em X-Attempt.

javascript
const crypto = require("crypto");

function assinaturaConfere(corpoCru, cabecalho, secret) {
  const m = /t=(\d+),v1=([a-f0-9]+)/.exec(cabecalho || "");
  if (!m) return false;
  const esperada = crypto
    .createHmac("sha256", secret)
    .update(`${m[1]}.${corpoCru}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(m[2]));
}

Responda 2xx. Qualquer outra coisa (ou silêncio por mais de 10s) vira retentativa: até 6 tentativas com espera crescente — 5s, 10s, 20s, 40s, 80s, 160s.

Trate como podendo repetir. Uma entrega repetida é normal (retentativa depois de um timeout que na verdade chegou). Use o id do evento como chave de idempotência.

Webhook não substitui a conferência. Se o seu servidor ficar fora do ar além das tentativas, o evento se perde — e o extrato continua lá, completo, como fonte de verdade. Uma consulta periódica de segurança é barata.

Cadastrou e não chega nada? GET /api/v1/cards/webhooks mostra lastFailureAt, lastFailureError e consecutiveFailures de cada destino.

Formato legado

Quem integrou antes dos destinos existirem continua recebendo CARD_TRANSACTION na URL de webhook de saque (ou na URL global do portal), assinado com X-Webhook-Signature em hex + X-Webhook-Timestamp. Assim que a conta cadastra o primeiro destino, os eventos passam a sair só no formato novo: o mesmo lançamento nunca é entregue nos dois formatos.

Bloqueio e cancelamento

Bloqueio de segurança da conta

Cartões fazem parte do mesmo controle de risco das saídas PIX. Quando o admin desativa o Pix Out da conta, todos os cartões ficam bloqueados automaticamente. A carga não é estornada nem creditada novamente na carteira: ela permanece intacta no cartão, mas sem autorizar compras.

Uma MED também pode imobilizar cartões quando o saldo da carteira não cobre o valor bloqueado. A Zypfy mantém R$ 1,00 fora do valor contabilizado como garantia, registra o restante como riskHold.heldCents e libera os cartões gradualmente conforme novos créditos recompõem a conta. Um cartão bloqueado manualmente antes da MED permanece bloqueado depois da regularização.

Enquanto riskHold.blocked=true, carga, cancelamento e desbloqueio pelo merchant são recusados com 409 CARD_RISK_HOLD. A liberação é automática e não deve ser forçada por polling.

Códigos importantes