Mobile Money Collections

Overview

The Mobile Money Collections guide walks you through the full lifecycle of accepting mobile money payments via the Cashless API.

1 - Initiate a Charge

To charge a customer, send a POST request to the initiate mobile money charge endpoint.

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
phoneNumber	String	✅	Recipient phone number in E.164 without plus (e.g. 254719624551)
momoOperatorId	String	❌	Mobile-money operator ID (required for all currencies except KES)
voucherPin	String	❌	12-digit OTT voucher PIN (required only if currency is BWP and using OTT vouchers)
walletCurrency	String	❌	Currency to settle funds into (defaults to currency)

Note: If currency is not KES, you must include momoOperatorId. If currency is BWP and processing an OTT payment, include voucherPin.

Example Request:

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

Example Response:

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

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

2 - Get Transaction Status

Always verify payment status before providing value. Use the get transaction endpoint with either the transactionId or your externalReference.

{
  "success": true,
  "data": {
    "transactionId": "lBK9bMny2gs4hLsG3XGq",
    "amount": 25,
    "type": "deposit",
    "currency": "KES",
    "chargeStatus": "successful",
    "status": "SUCCESSFUL",
    "method": "momo",
    "externalReference": "test",
    "phoneNumber": "254722416788"
  }
}

3 - Handle Webhooks

Configure webhooks to receive real-time updates. Set your webhook URL in the dashboard.

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "successful",
    "type": "deposit",
    "externalReference": "test",
    "method": "momo",
    "thirdPartReference": "TEQTEYRU"
  },
  "timestamp": "ISO-8601 timestamp"
}

If stepRequired is otp: Prompt the customer to enter the OTP from their phone.
If stepRequired is redirect: Redirect the customer to the provided redirectUrl.

4 - Validate OTP

If you receive a webhook with stepRequired: 'otp', collect the OTP and send it to the validate otp endpoint.

URL: /api/b2b/fiat/deposit/:transactionId/validate-otp

{
  "success": true,
  "message": "OTP validated successfully.",
  "transactionId": "123456789"
}

5 - Handle Redirects

When stepRequired is redirect, forward the customer to the redirectUrl to authorise the payment. Await the final webhook notification before providing value.