#The event
Register one HTTPS URL when the app is onboarded. PayGate POSTs JSON:
{
"id": "evt_...",
"type": "payment.succeeded",
"occurred_at": "2026-11-02T12:00:00.000Z",
"data": { "payment_id": "pay_...", "reference": "order-9f2c", "amount": 250000, "currency": "KES" }
}
#Headers
x-paygate-signature: t=1793641837,v1=<hex hmac>
x-paygate-event-id: evt_...
#Verifying the signature
Verify before parsing:
- Split
tandv1. - Reject if
abs(now - t) > 300seconds. - Compute
HMAC-SHA256(secret, t + "." + rawBody)and compare in constant time. - Deduplicate on
x-paygate-event-id.
Verify the raw body, never a re-serialised object: whitespace and key order change the digest.
#Retries
Respond 2xx quickly. Any other status is retried with backoff: 10s, 60s, 5m, 30m, 1h, 6h, 12h, 24h, then the event is marked dead and waits for a human in the console. Delivery is at least once, so make your handler idempotent.
#Event types
Event types: payment.succeeded, payment.failed, settlement.approved, settlement.failed, settlement.settled.