Step 1: Initiate Charge

Field	Type	Required	Description
`amount`	Number	✅	Amount to be charged (e.g. `1500`)
`currency`	String	✅	Currency code (e.g. `KES`)
`externalReference`	String	✅	Your own unique ID for reconciliation (e.g. invoice number)
`phoneNumber`	String	✅	Recipient phone number in E.164 without the plus (e.g. `254719624551`)
`momoOperatorId`	String	❌	Mobile-money operator ID (required for all currencies except `KES`)
`walletCurrency`	String	❌	Currency to settle funds into (defaults to the value of `currency`)

Note: If currency is not KES, you must include momoOperatorId.

To charge a customer, collect the required payment information and send it to the initiate mobile money charge endpoint.

Example Request:

{  
  "amount": 100,  
  "currency": "KES",  
  "externalReference": "order_12345",  
  "phoneNumber": "254719624551"  
}

Below is an example of the response:

{
  "success": true,
  "message": "Initiated request.",
  "transactionId": "123456789"
}

Note:Use the returned transactionId (or your externalReference) to track status.

2 - Get Transaction Status

Always verify the payment status before providing value to your customer. Use the get transaction endpoint with either:

The transactionId from the charge response or
Your externalReference

Here's an example of charge verification and response:

{
  "success": true,
  "data": {
    "transactionId": 'lBK9bMny2gs4hLsG3XGq',
    "amount": 25,
    "type": 'deposit',
    "currency": 'KES',
    "senderCurrency": 'KES',
    "senderAmount": 25,
    "receiverCurrency": 'KES',
    "receiverAmount": 25,
    "chargeStatus": 'successful',
    "status": 'SUCCESSFUL',
    "method": 'momo',
    "note": 'TFH174NFSJ Confirmed. Ksh25.00 sent to Honeycoin 722223344 on 17/06/25 at 1:17 AM. Transaction cost, Ksh0.00.',
    "fullTimestamp": '2025-06-17T01:16:44+03:00',
    "externalReference": "test",
    "thirdPartyReference": 'TFH174NFSJ',
    "phoneNumber": '+254722416788'
  }
}

{
  "success": true,
  "data": {
    "transactionId": '173675873400000038',
    "amount": 102,
    "type": 'deposit',
    "currency": 'KES',
    "senderCurrency": 'KES',
    "senderAmount": 102,
    "receiverCurrency": 'KES',
    "receiverAmount": 102,
    "chargeStatus": 'failed',
    "status": 'FAILED',
    "method": 'mpesa',
    "note": 'STK Prompt Time Out',
    "fullTimestamp": '2025-01-14T12:13:59+00:00',
    "externalReference": '173675873400000038',
    "phoneNumber": '254700000001'
  }
}

3 - Handle Webhooks

Configure webhooks to receive real-time transaction updates instead of polling the status endpoint.

Setup

Configure your webhook URL in your dashboard account.
Implement webhook endpoint security and validation.
Handle the webhook notifications in your application

Here's a sample of the webhook response:

{
  "event": "transaction_created",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "pending",
    "type": "withdrew",
    "externalReference": null
  },
  "timestamp": "2024-10-03T16:33:14.600Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "string",
    "status": "string",
    "type": "string",
    "externalReference": "string",
    "method": "string", // optional e.g momo, bank etc
    "thirdPartReference": "string" // optional. e.g Mpesa reference
  },
  "timestamp": "ISO-8601 timestamp"
}