Webhooks

NixPay posts payment events to your endpoint as they happen.

Event types

Event	When
`payment.initiated`	A payment request was accepted.
`payment.success`	The customer paid successfully.
`payment.failed`	The payment failed.
`payment.cancelled`	The customer cancelled.
`payment.timeout`	No result arrived in time.

Payload

{
  "event": "payment.success",
  "created_at": "2026-01-14T09:13:02+03:00",
  "data": {
    "reference": "NP-10021",
    "amount": 500,
    "currency": "KES",
    "status": "successful",
    "environment": "sandbox",
    "customer_phone": "2547••••••78",
    "mpesa_receipt": "QAB1C2D3E4",
    "result_code": "0",
    "result_desc": "The service request is processed successfully."
  }
}

Verifying signatures

Every delivery carries an HMAC-SHA256 signature of the raw body using your endpoint's signing secret.

X-NixPay-Event: payment.success
X-NixPay-Delivery: 1042
X-NixPay-Signature: sha256=5f3a…

Recompute the digest over the raw request body and compare in constant time.

Retries

Non-2xx responses are retried with exponential backoff (1m, 5m, 30m, 2h, 12h; five attempts). Every attempt is recorded in the delivery log with its response code and body.

Testing

Use Send test event on an endpoint to deliver a synthetic payment.success and inspect the result in the delivery log.

NixPay documentation · A Supreonix product Back to introduction