Mobile Money Collections

Description

The following endpoint is used to initiate a mobile money collection request.

Headers

The following headers should be added to your request.

Header	Type	Description	Required
accept	application/json	Expected response format	Yes
Content-Type	application/json	Content type of the request body	Yes
x-api-key	string	Your Lipila API key	Yes
callbackUrl	string	URL to receive asynchronous callback notifications	Optional

Request Body

The following properties should be present in your request body.

Field	Type	Description	Required
referenceId	string	Unique reference identifier for the transaction	Yes
amount	number	Amount to collect	Yes
narration	string	Description or note about the transaction	yes
accountNumber	string	Mobile money account number to collect from	Yes
currency	string	Currency code (e.g., ZMW)	Yes
email	string	Email address associated with the transaction	Optional

Example Request

This is an example request to create a mobile money payment.

curl -X 'POST' \
  'https://api.lipila.dev/api/v1/collections/mobile-money' \
  -H 'accept: application/json' \
  -H 'x-api-key: your_Secret_key' \
  -H 'callbackUrl: https://lipila.io/callback' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceId": "12345",  // Use this Id to check the transaction status.
  "amount": 1,
  "narration": "test",
  "accountNumber": "260xxxxxxxxx",
  "currency": "ZMW",
  "email": "johndoe@gmail.com"
  }'

INFO

Note MTN may sometimes delay to send prompts. when that happens dial *115#.

Example Successful Response

Below is a successful response which shows the transaction was created successfully.

HTTP Status Code	Description
200	SUCCESS

{
  "currency": "ZMW",
  "amount": 1, 
  "accountNumber": "260xxxxxxxxxx",
  "status": "Pending",
  "paymentType": "ZamtelKwacha",
  "ipAddress": "::1",
  "cardRedirectionUrl": null,
  "createdAt": "2025-10-01T10:24:56.605474+00:00",
  "referenceId": "f95a8f405ed1",
  "identifier": "LPLXC-20251001-2834" 
  "message": "Transaction Successful",
}

Error Codes

The following are the expected error responses from the api.

HTTP Status Code	Error Code	Description
400	BAD REQUEST	Missing or invalid request parameters
401	UNAUTHORIZED	Missing or invalid API authentication
403	FORBIDDEN	Access denied to this resource
500	SERVER_ERROR	Internal server error
429	TOO MANY REQUESTS	Rate limit exceeded, slow down requests

Example Failed Response

Here is what to expect when your transaction fails. Below are examples of failed transaction response. The message property is used here to describe the failure reason of a transaction.

MTN

{
  "referenceId": "000c291e430f",
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Failed",
  "paymentType": "MtnMoney",
  "type": "Collection",
  "ipAddress": "::ffff:10.109.2.19",
  "identifier": "LPLTXNCMM-20250820135741",
  "message": "LOW_BALANCE_OR_PAYEE_LIMIT_REACHED_OR_NOT_ALLOWED"
}

AIRTEL

{
  "referenceId": "a65a",
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Failed",
  "paymentType": "AirtelMoney",
  "type": "Collection",
  "ipAddress": "::1",
  "identifier": "LPLTXNCAM-20250818145802",
  "message": "User didn't enter the pin."
}

ZAMTEL

{
  "referenceId": "a8b8fb376832",
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Failed",
  "paymentType": "ZamtelKwacha",
  "type": "Collection",
  "ipAddress": "::ffff:10.109.2.19",
  "identifier": "LPLTXNCZK-20250821144612-C2FA2B72CF15",
  "message": "System internal error."
}