ZypfyDocs Acessar painel
Webhooks

Webhook: cartão virtual (enviado pela Zypfy ao seu servidor)

POSThttps://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

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

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.

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.

Corpo da requisição

Respostas

200Seu servidor responde 2xx para confirmar o recebimento.