Webhooks

Payment Failed Event

Receive webhook notifications when a payment fails or is reversed.

POST {your-webhook-url}

Headers

Header	Description
`x-hitchpay-signature`	HMAC SHA256 signature — verify before processing

Payload Example

{
  "event": "payment.failed",
  "data": {
    "reference": "HCHK380B3716D4",
    "status": "failed",
    "amount": "100.00",
    "currency": "NGN",
    "failure_reason": "Insufficient funds",
    "customer": {
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  },
  "sent_at": "2025-11-06T02:00:00.000Z"
}

Expected Response

Your endpoint must return HTTP 200 OK to acknowledge receipt.

{ "status": "ok" }

See Webhook Overview for signature verification and retry schedule.

Questions? Email [email protected]. Also on GitBook.