Lipa Na M-Pesa Verification

Verify a Kenyan M-Pesa paybill or till number and retrieve the registered business 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/lipa-na-mpesa \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "247247",
    "identifierType": "4"
  }'

Request fields

Field	Type	Required	Description
`identifier`	string	Yes	Paybill number or till number
`identifierType`	string	Yes	`"4"` for Paybill, `"2"` for Till
`mode`	string	No	`sync` (default) or `async`
`webhookUrl`	string	No	Required when `mode` is `async`

Successful response

{
  "id": "ver_a1b2c3d4-...",
  "status": "success",
  "verificationType": "LIPA_NA_MPESA",
  "identifier": "247247",
  "verifiedAt": "2026-03-09T10:05:00.000Z",
  "verified": true,
  "businessName": "Safaricom PLC"
}

Response fields

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

Error codes

`error.code`	Cause	Action
`ACCOUNT_NOT_FOUND`	Paybill or till number 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

Next steps

M-Pesa Agent — verify an M-Pesa agent
Async Verification — receive results via webhook
Errors — full error code reference

Overview

M-Pesa Agent