Transaction result callback

POST

When a transaction reaches a final state, PayHero sends an HTTP POST to the callback_url supplied on the original request. Respond with 200 OK to acknowledge receipt.

• transaction_type is inbound_payment for collections (pay-in) and outbound_payment for disbursements (pay-out).
• status is success or failed; success is a boolean mirror.
• Match the notification to your record using external_reference (your reference) or reference (the PayHero merchant reference).

Authorizations

• basicAuth

Request Body^required

Media typeapplication/json

Asynchronous transaction result notification sent to your callback_url.

object

success

boolean

status

string

Allowed values: success failed

message

string

reference

PayHero merchant reference.

string

external_reference

Your reference, echoed back.

string

amount

number

currency

string

transaction_id

string

transaction_date

string format: date-time

transaction_type

string

Allowed values: inbound_payment outbound_payment

provider_reference

string

provider

string

callback_urls

Array<string> | null

Examples

Collection succeeded (inbound)

{
  "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
}

Collection failed (cancelled by user)

{
  "success": false,
  "status": "failed",
  "message": "Request Cancelled by user.",
  "reference": "UFD00452113.iI",
  "external_reference": "test_ext",
  "amount": 1,
  "currency": "KES",
  "transaction_id": "",
  "transaction_date": "2026-06-30T00:45:21Z",
  "transaction_type": "inbound_payment",
  "provider_reference": "",
  "provider": "mpesa_dc",
  "callback_urls": null
}

Disbursement succeeded (outbound)

{
  "success": true,
  "status": "success",
  "message": "Transaction processed successfully.",
  "reference": "UFD004139536.eO",
  "external_reference": "TX1234ABCre55AH",
  "amount": 10,
  "currency": "KES",
  "transaction_id": "txn_d0affc67-6fc6-4741-bd09-f32f7c181416",
  "transaction_date": "2026-06-30T00:41:39Z",
  "transaction_type": "outbound_payment",
  "provider_reference": "UFUSB1OXWV",
  "provider": "sasapay",
  "callback_urls": null
}

Responses

200

Acknowledge receipt of the callback.