Disbursements

Disbursements are payments made to your customers. Lipila supports disbursements to mobile money accounts in Zambia.

Mobile Money Disbursements

Disbursement Parameters

To initialize the transaction, you need to pass information such as currency, amount, accountNumber, narration, etc. The key, currency, amount, accountNumber and phoneNumber parameters are the only required parameters. The table below lists the parameters that you can pass when initializing a transaction.

Parameter	Type	Required?	Description
secret_key	string	yes	The secret key of your Lipila account
currency	string	yes	The currency code of the payment amount
amount	double	yes	The payment amount to be charged
accountNumber	string	yes	The account number of the customer
fullName	string	no	The full name of the customer
phoneNumber	string	yes	The phone number of the customer
email	string	no	The email address of the customer (optional)
externalId	string	no	The external ID of the payment (optional)
narration	string	no	The payment description (optional)

Here’s how to use the Lipila API to accept a mobile money payment

curl --location --request POST 'https://lipila-uat.hobbiton.app//transactions/mobile-money/disburse' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "currency": "ZMW",
  "amount": 1.00,
  "accountNumber": "260971042607",
  "fullName": "Vincent Musangu",
  "phoneNumber": "260977777777",
  "email": "vincent@gmail.com",
  "externalId": "32142",
  "narration": "Payment For Bread"
}'

Make sure to replace YOUR_SECRET_KEY with your Lipila secret key.

Response For Disbursement Transactions

The Lipila API returns a JSON response with the following fields:

Field	Type	Description
status	string	The status of the transaction
message	string	The message of the transaction
transactionId	string	The transaction ID of the transaction
externalId	string	The external ID of the transaction
amount	double	The amount of the transaction

Successful Response Status Code

Code	Description
201	Created

Here’s an example of a Transaction sent for processing response:

{
  "amount": 1,
  "transactionId": "LPLTXN23103109322849382",
  "externalId": "974632",
  "status": "Pending",
  "message": "Transaction sent for processing"
}

CallBack Response for Disbursement Transactions

{
  "status": "Successful",
  "paymentType": "MtnMoney",
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "260977138264",
  "customer": {
    "fullName": "John Doe",
    "phoneNumber": "260977138264",
    "email": "johndoe@gmail.com"
  },
  "ipAddress": "193.387.1.31",
  "message": "Disbursement successful",
  "transactionId": "LPLTXN23103109322849382",
  "externalId": "4860326"
}