Mobile Money Disbursement

Description

This endpoint is used to initiate a mobile money disbursement.

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

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

Example Request

curl -X 'POST' \
  'https://api.lipila.dev/api/v1/disbursements/mobile-money' \
  -H 'accept: application/json' \
  -H 'callbackUrl: https://lipila.io/callback' \
  -H 'x-api-key: Your_secret_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceId": "b05bad241fd1", // Use this Id to check the transaction status
  "amount": 1,
  "narration": "test",
  "accountNumber": "260xxxxxxxxxx",
  "currency": "ZMW"
}'

Example Successful Response

Below is a successful response from the above request. This successful response indicates that a disbursement has been created successfully.

HTTP Status Code	Description
200	SUCCESS

{
  "amount": 1,
  "externalId": null,
  "narration": "test",
  "ipAddress": "::1",
  "referenceId": "a9a2",
  "status": "Pending",
  "currency": "ZMW",
  "type": "Disbursement",
  "accountNumber": "260xxxxxxxxxx",
  "paymentType": "MtnMoney",
  "createdAt": "2025-10-01T13:05:37.869722+00:00",
  "identifier": "LPLXC-20251001-6965"
}

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
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": "f9b3b3b248c5",
  "currency": "ZMW",
  "amount": 0.5,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Failed",
  "paymentType": "MtnMoney",
  "type": "Disbursement",
  "ipAddress": "::ffff:10.109.2.19",
  "identifier": "LPLXC-20250910-3083",
  "message": "Failed to send status check to Mtn httpStatusCode=404"
}

AIRTEL

{
  "referenceId": "fff0c44dd15d",
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Failed",
  "paymentType": "AirtelMoney",
  "type": "Disbursement",
  "ipAddress": "::1",
  "identifier": "LPLTXNDAM-20250827125439",
  "message": "Transaction is not found"
}

ZAMTEL

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