Accept Payments

Accepting payments with Lipila is a simple and straightforward process. Our payment gateway provides a range of APIs and SDKs that make it easy to integrate with your existing website or app, and we support a variety of payment methods to make it convenient for your customers to pay.

Mobile Money Payments

Payment 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' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "currency": "ZMW",
  "amount": 1.00,
  "accountNumber": "260971042607",
  "fullName": "Vincent Musangu",
  "phoneNumber": "260971042607",
  "email": "vincent@gmail.com",
  "externalId": "32142",
  "narration": "Payment For Bread"
}'

Make sure to replace YOUR_SECRET_KEY with your Lipila secret key.

Response For Airtel and MTN Payment 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:

{
  "status": "Pending",
  "message": "Transaction sent for processing",
  "transactionId": "123456789",
  "externalId": "32142",
  "amount": 1.0
}

CallBack Response for Airtel and MTN Transactions

{
  "status": "Successful",
  "paymentType": "MtnMoney",
  "currency": "string",
  "amount": 0,
  "accountNumber": "string",
  "customer": {
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string"
  },
  "ipAddress": "string",
  "message": "string",
  "transactionId": "string",
  "externalId": "string"
}

Zamtel Response

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

Field	Value
status	Successful
paymentType	ZamtelKwacha
currency	string
amount	0
accountNumber	string
customer
fullName	string
phoneNumber	string
email	string
ipAddress	string
message	string
transactionId	string
externalId	string

Successful Response Status Code

Code	Description
201	Created

Here’s an example of a Transaction response for zamtel payment:

{
  "status": "Successful",
  "paymentType": "ZamtelKwacha",
  "currency": "string",
  "amount": 0,
  "accountNumber": "string",
  "customer": {
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string"
  },
  "ipAddress": "string",
  "message": "string",
  "transactionId": "string",
  "externalId": "string"
}

Card Payments

Payment Parameters

Parameter	Type	Required	Description
currency	string	Yes	The currency of the transaction
amount	number	Yes	The amount of the transaction
phoneNumber	string	Yes	The phone number associated with the account
email	string	No	The email address associated with the account
customerFirstName	string	No	The first name of the customer
customerLastName	string	No	The last name of the customer
customerCity	string	No	The city of the customer
customerCountry	string	No	The country of the customer
customerAddress	string	No	The address of the customer
customerZip	number	No	The ZIP code of the customer
externalId	string	No	The external ID of the transaction
narration	string	No	Additional information or notes about the transaction

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

curl --location --request POST 'hhttps://lipila-uat.hobbiton.app/transactions/card' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "currency": "ZMW",
  "amount": 0,
  "phoneNumber": "string",
  "email": "string",
  "customerFirstName": "string",
  "customerLastName": "string",
  "customerCity": "string",
  "customerCountry": "string",
  "customerAddress": "string",
  "customerZip": 0,
  "externalId": "string",
  "narration": "string"
}'

Make sure to replace YOUR_SECRET_KEY with your Lipila secret key.

Response For Card Payment Transactions

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

Parameter	Type
status	string
paymentType	string
currency	string
amount	number
accountNumber	string
customer	object
fullName	string
phoneNumber	string
email	string
ipAddress	string
message	string
transactionId	string
externalId	string
redirectUrl	string

Successful Response Status Code

Code	Description
201	Created

Here’s an example of a Transaction processed response for card payment:

{
  "status": "Pending",
  "paymentType": "AirtelMoney",
  "currency": "string",
  "amount": 0,
  "accountNumber": "string",
  "customer": {
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string"
  },
  "ipAddress": "string",
  "message": "string",
  "transactionId": "string",
  "externalId": "string",
  "redirectUrl": "string"
}