HyzePay
Dashboard

Eventos · Pagamentos

Pagamentos

Eventos de cobrança PIX (API v1, links e checkouts). O evento crítico para liberar produto é payment.paid.

Valide HMAC, confira status === "paid" e use external_id para amarrar ao pedido interno. Idempotência por event.id.

Eventos

EventoQuandoUso
payment.createdPagamento criado (API)Log / analytics
payment.paidPagamento confirmadoLiberar produto / crédito
payment.expiredPendente expirouLiberar estoque
payment.failedFalha no processamentoNotificar usuário
payment.refundedEstornoRevogar acesso

Payload payment.paid

Campos em data.object (v2):

CampoTipoDescrição
idstringUUID do pagamento
statusstringDeve ser paid
amount_centsnumberCentavos
external_idstring | nullSeu ID
payment_methodstringpix, card…
customerobjectname, email, document, phone
metadataobject | nullJSON livre
paid_atstring | nullISO

Regras para liberar o produto

  1. Assinatura HMAC válida
  2. type === payment.paid
  3. status === paid
  4. Confira amount_cents se souber o valor
  5. Use external_id ou id
  6. Ignore event.id já processado
  7. Responda 200 rápido

Handler de exemplo

async function handleHyzePayWebhook(event: any) {
  const type = event.type || event.event;
  const payment =
    event.api_version === "v1" || event.event
      ? event.data
      : event.data?.object;

  if (type !== "payment.paid") return;
  if (payment?.status !== "paid") throw new Error("Status inválido");

  const orderKey = payment.external_id || payment.id;
  await markOrderPaidInMySystem({
    orderKey,
    amountCents: payment.amount_cents,
    hyzePayId: payment.id,
    eventId: event.id || event.event_id,
  });
}