Mobile Money (M-Pesa)
Verify Kenyan M-Pesa paybill numbers, till numbers, and agents before sending money to them.
| Verification | Endpoint | Returns |
|---|---|---|
| Lipa Na M-Pesa | POST /verify/lipa-na-mpesa | Registered business name |
| M-Pesa Agent | POST /verify/mpesa-agent | Registered agent name |
Prerequisites
You'll need an API key. See Quickstart or Authentication if you don't have one yet.
Note
Verification endpoints use an API key in the X-API-Key header, not a Bearer token. Verification POST requests also require an Idempotency-Key header.
Verify a paybill or till number
Terminal
curl -X POST https://api.lira.com/api/v1/verify/lipa-na-mpesa \
-H "X-API-Key: YOUR_API_KEY" \
-H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "247247",
"identifierType": "paybill"
}'| Field | Type | Required | Description |
|---|---|---|---|
identifier | string | Yes | Paybill number or till number |
identifierType | string | Yes | "paybill" or "till" |
mode | string | No | sync (default) or async |
webhookUrl | string | No | Required when mode is async |
Response
JSON
{
"id": "a1b2c3d4-...-...-...-...",
"status": "success",
"verificationType": "LIPA_NA_MPESA",
"identifier": "247247",
"verifiedAt": "2026-03-09T10:05:00.000Z",
"verified": true,
"businessName": "Safaricom PLC"
}businessName is the registered business name, or null if unavailable. verified is true when the number is registered and active.
Verify an M-Pesa agent
Terminal
curl -X POST https://api.lira.com/api/v1/verify/mpesa-agent \
-H "X-API-Key: YOUR_API_KEY" \
-H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentCode": "123456"
}'| Field | Type | Required | Description |
|---|---|---|---|
agentCode | string | Yes | M-Pesa agent code |
mode | string | No | sync (default) or async |
webhookUrl | string | No | Required when mode is async |
Response
JSON
{
"id": "a1b2c3d4-...-...-...-...",
"status": "success",
"verificationType": "MPESA_AGENT",
"identifier": "123456",
"verifiedAt": "2026-03-09T10:05:00.000Z",
"verified": true,
"agentName": "John Kamau"
}agentName is the registered agent name, or null if unavailable. verified is true when the agent code is registered and active.
Error handling
Both endpoints share the same error codes:
error.code | Cause | Action |
|---|---|---|
ACCOUNT_NOT_FOUND | Paybill, till, or agent code not found | Ask the user to confirm the number |
PROVIDER_ERROR | Upstream M-Pesa system error | Retry with exponential backoff |
PROVIDER_TIMEOUT | Upstream system timed out | Retry; transient error |