Callbacks & Webhooks

PayHero delivers the final result of a transaction asynchronously by sending an HTTP POST to the callback_url you provide on each request.

Acknowledge the callback

Respond with 200 OK as soon as you have stored the notification. Do the heavy work (fulfilment, ledger updates) after acknowledging.

Payload

{
  "success": true,
  "status": "success",
  "message": "The service request is processed successfully.",
  "reference": "UFD004453187.iI",
  "external_reference": "test_ext",
  "amount": 1,
  "currency": "KES",
  "transaction_id": "",
  "transaction_date": "2026-06-30T00:44:53Z",
  "transaction_type": "inbound_payment",
  "provider_reference": "UFU51A2XO2",
  "provider": "mpesa_dc",
  "callback_urls": null
}

Key fields

Field	Meaning
`status`	`success` or `failed` (`success` is a boolean mirror)
`transaction_type`	`inbound_payment` (pay-in) or `outbound_payment` (pay-out)
`external_reference`	Your reference, echoed back — use it to match your record
`reference`	PayHero merchant reference
`provider_reference`	The provider’s reference (present on success)

Failed example

A user-cancelled collection arrives as:

{
  "success": false,
  "status": "failed",
  "message": "Request Cancelled by user.",
  "reference": "UFD00452113.iI",
  "external_reference": "test_ext",
  "transaction_type": "inbound_payment",
  "provider": "mpesa_dc"
}

See the API Reference → Callbacks for the full schema and all examples.