DocsTableau de bord

GuidesFiabilitéÉvénements

Événements

PayHaze vous prévient de chaque changement par une notification signée, renvoyée tant que votre site ne l’a pas acceptée.

Déclarer une destination

Dans Développeurs, puis Notifications : une adresse HTTPS et sa clé de signature pos_whsec_…, montrée une fois.

Trois types, de la même forme : payment.updated, refund.updated et dispute.updated. payment_id et state sont toujours au premier niveau ; state est l’état de ce que dit l’événement (le paiement, le remboursement ou le litige).

Corps d’une notificationJSON
{
  "id": "evt_5d1c…",
  "type": "refund.updated",
  "merchant_id": "mrc_…",
  "environment": "test",
  "created_at": "2026-10-06T09:12:44.512+00:00",
  "payment_id": "pay_7c1e…",
  "state": "SUCCEEDED",
  "data": { "refund_id": "ref_9a2b…", "amount_minor": "2490", "currency": "EUR", "origin": "payment_os" }
}
  • payment.updated : data est vide ; relisez le paiement (GET /v1/payment-intents/{id}) pour le reste
  • refund.updated : data = refund_id, amount_minor (en centimes, en texte), currency, origin
  • dispute.updated : data = dispute_id, status, reason, amount_minor, currency, due_by
  • id est aussi dans l’en-tête PayHaze-Event-ID

Vérifier la signature

En-têtes : PayHaze-Event-ID, PayHaze-Delivery-ID, PayHaze-Attempt et PayHaze-Signature, de la forme t=<millisecondes>,v1=<hex>. Le message signé en HMAC-SHA256 est l’horodatage, un point, l’identifiant d’événement, un point, puis le corps brut.

VérificationNode.js
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(raw, eventId, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = createHmac("sha256", secret).update(parts.t + "." + eventId + "." + raw).digest("hex");
  const age = Math.abs(Date.now() - Number(parts.t));
  return age < 5 * 60_000 && header.split(",").filter(p => p.startsWith("v1="))
    .some(p => p.length === expected.length + 3 && timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}

Doublons et rediffusion

Un même événement peut arriver deux fois : dédupliquez sur PayHaze-Event-ID. Une livraison rediffusée garde son identifiant et son corps, et ne déclenche jamais de nouveau débit.