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
- Sua conta precisa estar ativa, aprovada e com saídas habilitadas.
- Autentique-se normalmente em
POST /api/auth/logine envie o token Bearer. - Todos os valores do produto de cartões são inteiros em centavos.
- A carga mínima é
500(R$ 5,00) e a máxima é5000000(R$ 50.000,00). - Emissão e carga consomem o saldo disponível da carteira Zypfy.
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:
- emissão: valor fixo por cartão (
issue.feeCents); - carga/aumento de limite: o maior valor entre um percentual e um piso
(
load.percent/load.minimumCents); - compra aprovada: o maior valor entre
purchase.percentepurchase.fixedCents. Quando os dois vêm zerados, a conta é isenta e a compra não gera segundo débito.
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
- Consulte as tarifas.
- Emita o cartão com
POST /api/v1/cards. - Revele PAN/CVV somente quando o portador solicitar.
- Carregue o cartão com
POST /api/v1/cards/{cardId}/load. - Cadastre um destino de webhook (
POST /api/v1/cards/webhooks) para receber compra, recusa e estorno na hora. - Acompanhe compras em
GET /api/v1/cards/{cardId}/transactionsou no histórico global — o extrato continua sendo a fonte de verdade e a rede de segurança. - Bloqueie temporariamente quando necessário; cancele somente de forma definitiva.
Emissão
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
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:
- banco de dados, localStorage ou cache;
- logs e ferramentas de observabilidade;
- analytics, gravação de sessão ou suporte;
- webhooks próprios ou de terceiros.
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.
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} removeCadastrar
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
| event | Quando dispara |
|---|---|
card.issued | Cartão emitido |
card.load.completed | Carga concluída — o saldo já está no cartão |
card.load.failed | Carga não se concretizou; o valor voltou para o seu saldo |
card.purchase.approved | Compra aprovada |
card.purchase.declined | Compra recusada. Evento próprio: você não precisa inspecionar o corpo para saber se deve agir |
card.purchase.updated | A 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.refund | Estorno da loja creditado no cartão — dinheiro de volta, entra no saldo |
card.reversal | Autorizaçã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.settlement | Liquidação de uma compra já avisada. Mesmo dinheiro — não debite de novo |
card.verification | Checagem de R$ 0,00 (cadastro em carteira digital, cartão on-file) |
card.issuer_fee | IOF ou spread de compra internacional |
card.status_changed | Cartã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.
{
"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.
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
block: impede novas compras e pode ser revertido comunblock.cancel: é definitivo. O limite disponível retornado pela adquirente volta para a carteira Zypfy; tarifas de emissão/carga e valores já gastos não são estornados.- O cancelamento pode retornar HTTP 409 enquanto existir autorização pendente.
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
400 INSUFFICIENT_BALANCE: saldo insuficiente para principal + tarifas.403 KYC_REQUIRED: conta ainda não aprovada.403 WITHDRAWAL_DISABLED: saídas desabilitadas para a conta.404 CARD_NOT_FOUND: cartão inexistente ou pertencente a outro merchant.409 CARD_NOT_ACTIVE: carga permitida apenas em cartão ativo.409 CARD_RISK_HOLD: cartão imobilizado por MED ou pelo bloqueio de Pix Out.400 INVALID_WEBHOOK_URL: destino precisa ser https, host público, porta 443 ou 8443.400 INVALID_WEBHOOK_EVENTS:eventstraz evento fora da lista aceita.404 WEBHOOK_NOT_FOUND: destino inexistente ou de outro merchant.409 WEBHOOK_ALREADY_EXISTS: a mesma url já está cadastrada nesse escopo.409 WEBHOOK_LIMIT_REACHED: limite de 20 destinos por conta.429 RATE_LIMITED: aguarde antes de repetir.503 PROVIDER_UNAVAILABLE: indisponibilidade temporária; retente com backoff e a mesma chave idempotente.