PayZu PixCertificados e segurança

Assinatura dos callbacks


Confira a assinatura de cada aviso para ter certeza de que ele veio da PayZu e de que o corpo não foi alterado no caminho.

Como a assinatura é calculada

O valor v1 é um HMAC-SHA256, em hexadecimal, calculado sobre o timestamp t (Unix, em segundos), um ponto e o corpo enviado:

X-Callback-Signature
t=1760140800, v1=5f1c2e9a0b7d4c6e8f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70
v1 = hex(HMAC_SHA256(segredo, "1760140800." + corpo))
CanalSegredo
callbackUrlO da conta, criado em Segredo dos callbacks. Enquanto a conta não cria o segredo, esses avisos saem sem assinatura.
WebhookO de cada webhook, gerado no cadastro ou em rotate-secret.

A entrega não informa de qual webhook veio, então use uma URL por webhook para saber qual segredo aplicar.

receber-aviso.js
import crypto from 'node:crypto'
import http from 'node:http'

// Uma rota por canal: cada uma valida com o seu segredo.
const SECRETS = {
  '/payzu/callback': process.env.PAYZU_CALLBACK_SECRET,
  '/payzu/webhook': process.env.PAYZU_WEBHOOK_SECRET,
}
const TOLERANCE_SECONDS = 300
const SIGNATURE = /^t=(\d+),\s*v1=([0-9a-f]{64})$/

function isAuthentic(secret, header, raw) {
  const match = SIGNATURE.exec(header ?? '')
  if (!secret || !match) return false
  const [, t, v1] = match
  if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false
  const mac = crypto.createHmac('sha256', secret).update(`${t}.`).update(raw).digest()
  return crypto.timingSafeEqual(mac, Buffer.from(v1, 'hex'))
}

http.createServer(async (req, res) => {
  const chunks = []
  for await (const chunk of req) chunks.push(chunk)
  const raw = Buffer.concat(chunks)
  if (!isAuthentic(SECRETS[req.url], req.headers['x-callback-signature'], raw)) {
    res.writeHead(401).end()
    return
  }
  const notice = JSON.parse(raw)
  // Mesmo aviso, mesma chave: retentativa, reenvio ou os dois canais.
  const key = notice.infraction
    ? `${notice.infraction.id}:${notice.infraction.updatedAt}`
    : `${notice.id}:${notice.updatedAt}`
  try {
    // Grave numa tabela com a chave única ou numa fila durável; chave repetida não é erro.
    await storeOnce(key, req.headers['x-callback-event'] ?? 'callbackUrl', notice)
  } catch {
    res.writeHead(500).end()
    return
  }
  res.writeHead(200).end()
}).listen(3000)

Calcule o HMAC sobre os bytes recebidos.

A PayZu assina o resultado de JSON.stringify do corpo, os mesmos bytes que envia. Se o seu framework interpretar e reserializar o JSON, espaços e ordem das chaves podem mudar e a assinatura deixa de conferir.

Compare t com o seu relógio e recuse avisos com mais de 5 minutos de diferença. Cada tentativa sai com um t novo, então essa janela não barra retentativas.

Responda depois de gravar

A PayZu espera a resposta por até 5 segundos e, sem 2xx, tenta de novo. Grave o aviso numa tabela ou numa fila durável, responda 2xx e processe depois. Se a gravação falhar, responda com erro para o aviso voltar na próxima tentativa.

O mesmo aviso pode chegar mais de uma vez.

Isso acontece por retentativa, reenvio ou pelos dois canais, inclusive dentro da janela de 5 minutos. Deduplique os avisos de transação por id + updatedAt e os de INFRACTION_CHANGED só por infraction.id + infraction.updatedAt. Veja Webhooks e callbacks.