Webhook: cartão virtual (enviado pela Zypfy ao seu servidor)
https://seusite.com/webhooks/zypfysua URL de callback (clientCallbackUrl ou a configurada no painel)Este endpoint é hospedado pelo seu servidor, não pela Zypfy.
Cadastre a URL em POST /api/v1/cards/webhooks
(ou mande webhookUrl na emissão do cartão) e a Zypfy avisa a cada
evento do cartão, em vez de você consultar o extrato de tempos em tempos.
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 |
Conferindo a assinatura
Toda entrega leva X-Webhook-Signature no formato t=<epoch>,v1=<hmac>.
O HMAC é SHA-256 de <t>.<corpo cru> com o secret daquele destino
(devolvido uma única vez, no cadastro). 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.
Corpo da requisição
idstring (uuid)obrigatórioId do evento — use como chave de idempotência.
eventstringobrigatórioexemplo:card.purchase.approvedsentAtstring (date-time)obrigatóriocardobjectobrigatóriocampos de card
idstring (uuid)last4string | nullnicknamestring | nullstatusstring | null
transaction| nullExatamente a mesma linha que o extrato devolveria. Em
card.status_changedvemnull— não há dinheiro envolvido.campos de transaction
idstring (uuid)obrigatóriocardIdstring (uuid)obrigatóriocardLast4string | nullexemplo:4242cardNicknamestring | nullexemplo:MarketingtypestringobrigatórioISSUEemissão ·LOADcarga ·PURCHASEcompra ·REFUNDestorno ·VERIFICATIONchecagem de R$ 0,00 feita por uma plataforma ao cadastrar o cartão ·SETTLEMENTliquidação de uma compra que já está na lista ·ISSUER_FEEIOF/spread da compra internacional. Trate a lista como aberta: tipos novos podem entrar.exemplo:PURCHASEsourcestring | nullISSUERevento do cartão na rede ·GATEWAYoperação sua sobre o cartão.valores:ISSUERGATEWAYstatusstringCOMPLETE·DECLINED(recusada pela rede) ·PENDING/FAILED(operação em curso ou que não se concretizou).exemplo:COMPLETEdirectionstring | nullSinal do lançamento.
amountCentsé sempre positivo.valores:DEBITCREDITNONEaffectsBalancebooleanSe ESTA linha move o saldo do cartão. Some só as linhas com
true.exemplo:trueaccountDebitCentsintegerQuanto esta linha tirou do saldo da sua carteira Zypfy (não do cartão). Na compra é só a tarifa; na carga é valor + tarifa. Negativo quando o dinheiro voltou.
exemplo:80feeChargedFromstring | nullTarifa Zypfy nunca é debitada do cartão, e sim do saldo da conta.
exemplo:ACCOUNT_BALANCEdescriptionstring | nullTexto pronto da linha.
exemplo:META PLATFORMSamountCentsintegerobrigatórioSempre positivo; quem dá o sentido é
direction.exemplo:12990authorizedAmountCentsinteger | nullDifere de
amountCentsquando a loja captura menos do que autorizou (hotel, posto).originalAmountCentsinteger | nullValor de ORIGEM, só quando houve conversão (compra internacional).
exemplo:580originalCurrencystring | nullexemplo:USDcurrencystringobrigatórioCódigo numérico ISO 4217 (986 = BRL).
exemplo:986billingCurrencystring | nullMoeda em que o cartão foi debitado.
exemplo:BRLapprovedbooleanobrigatóriofalseem compra ou verificação recusada — a recusa aparece no extrato como qualquer outra linha, não move saldo e não gera tarifa.exemplo:truedeclineReasonstring | nullresponseCodestring | nullResultado da tentativa no padrão ISO 8583.
exemplo:0responseMessagestring | nullexemplo:AprovadamerchantNamestring | nullDescritor real informado pela bandeira; nunca substituído por rótulo nosso.
exemplo:META PLATFORMSmerchantCitystring | nullexemplo:SAO PAULOmerchantCountrystring | nullexemplo:BRAmccstring | nullexemplo:7311merchantCategorystring | nullexemplo:Publicidade e anúnciosentryModestring | nullexemplo:Compra onlinerecurringboolean | nulltrueem cobrança recorrente (assinatura).acquirerMerchantIdstring | nullacquirerCountrystring | nullexemplo:SGPauthorizationCodestring | nullCódigo da compra na rede — é o que se informa numa contestação.
clearedboolean | nullreversedboolean | nullfeeCentsintegerobrigatórioTarifa Zypfy deste lançamento. Cobram tarifa a compra e a verificação; não cobram estorno, recusa, liquidação nem o encargo da compra internacional.
exemplo:80relatedToobject | nullDe qual lançamento este é consequência.
campos de relatedTo
relationstringvalores:SETTLEMENT_OFFEE_OFidstring (uuid)merchantNamestring | nullamountCentsinteger
localTimestring (date-time) | nullHora informada pela loja; pode diferir de
occurredAt.settledAtstring (date-time) | nullupdatedAtstring (date-time) | nullÚltima vez que a rede reprocessou o lançamento. Reconcilie por este campo, não só por
occurredAt.occurredAtstring (date-time)obrigatório