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).
{
"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.
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.