Verifications

Verify an M-Pesa agent

post/verify/mpesa-agent

Verify a Kenyan M-Pesa agent by agent code.

Authorization

API key in the X-API-Key header.

Headers

Idempotency-Keystringrequired

Required for verification mutations. Use a unique printable ASCII key per logical request; retries with the same key return the original response.

Body required

agentCodestringrequired

M-Pesa agent code to verify

countrystring

ISO 3166-1 alpha-2 country code. Defaults to KE.

modestring

`sync` returns the verification result in the response. `async` returns `pending` and delivers the final result via your registered webhooks (configure under `/webhooks`).

Options: syncasync

Response

idstringrequired

statusstringrequired

Options: pendingsuccessfailederrorinconclusive

verificationTypestringrequired

Options: MPESA_AGENT

identifierstringrequired

countrystringrequired

verifiedAtstring | nullrequired

verifiedboolean | nullrequired

originstringrequired

Where this verification was initiated. `api` = Lira API key (machine-to-machine). `dashboard` = logged-in dashboard user.

Options: apidashboard

agentCodestring | nullrequired

agentNamestring | nullrequired

agentAccountstring | nullrequired

errorobject | nullrequired

Populated only when status is `failed` or `error`

Show child attributes

codestringrequired

messagestringrequired

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", "country": "KE", "mode": "sync" }'

const response = await fetch('https://api.lira.com/api/v1/verify/mpesa-agent', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ "agentCode": "123456", "country": "KE", "mode": "sync" }), }); const data = await response.json();

import requests response = requests.post( "https://api.lira.com/api/v1/verify/mpesa-agent", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "agentCode": "123456", "country": "KE", "mode": "sync" }, ) data = response.json()

{ "id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "status": "success", "verificationType": "MPESA_AGENT", "identifier": "123456", "country": "KE", "verifiedAt": "2026-04-22T10:15:30.000Z", "verified": true, "origin": "api", "agentCode": "123456", "agentName": "Jane Doe Enterprises", "agentAccount": "0712345678", "error": { "code": "AGENT_NOT_FOUND", "message": "Agent code not registered with M-Pesa" } }

{ "message": "NG Account Number verification is not enabled for your organisation.", "code": "SERVICE_NOT_ENABLED", "action": { "type": "CONTACT_ADMIN", "hint": "Ask your administrator to enable NG Account Number verification in the Lira dashboard." } }