M-Pesa Agent Verification

Verify a Kenyan M-Pesa agent by agent code and retrieve the registered agent name.

Prerequisites

You'll need an API key. See API Keys to generate one.

Note: Verification endpoints use an API key in the X-API-Key header — not a Bearer token.

Make the request

curl -X POST https://api.lira.com/api/v1/verify/mpesa-agent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentCode": "123456"
  }'

Request fields

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`

Successful response

{
  "id": "ver_a1b2c3d4-...",
  "status": "success",
  "verificationType": "MPESA_AGENT",
  "identifier": "123456",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": true,
  "agentName": "John Kamau"
}

Response fields

Field	Type	Description
`id`	string	Unique verification ID
`status`	string	`success`, `failed`, `pending`, or `error`
`verificationType`	string	Always `MPESA_AGENT`
`identifier`	string	The agent code submitted
`verifiedAt`	string	ISO 8601 timestamp when verification completed
`verified`	boolean	`true` if the agent code is registered and active
`agentName`	string	Registered agent name, or `null` if unavailable

Error codes

`error.code`	Cause	Action
`ACCOUNT_NOT_FOUND`	Agent code not found	Ask the user to confirm the agent code
`PROVIDER_ERROR`	Upstream M-Pesa system error	Retry with exponential backoff
`PROVIDER_TIMEOUT`	Upstream system timed out	Retry — transient error

Next steps

Lipa Na M-Pesa — verify a paybill or till number
Async Verification — receive results via webhook
Errors — full error code reference

Lipa Na M-Pesa

Overview