Card Collections

Lipila provides payments by Visa and Master Cards.

Description

This endpoint is used to initiate a card collection.

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
firstName	string	Customer's first name	Yes
lastName	string	Customer's last name	Yes
phoneNumber	string	Customer's phone number	Yes
referenceId	string	Unique reference identifier for the transaction.	Yes
amount	number	Amount to collect	Yes
accountNumber	string	Card number or account identifier to collect from	Yes
currency	string	Currency code (e.g., ZMW)	Yes
email	string	Customer's email address	Yes
narration	string	Customer's email address	Yes
city	string	Customer's city	Yes
country	string	Customer's country code e.g. ZM	Yes
address	string	Customer's address	Yes
zip	string	Customer's postal/zip code	Yes
backUrl	string	URL to navigate back to after unsuccessful payment	Yes
redirectUrl	string	URL to redirect customer after payment	Yes

Example Request

curl -X 'POST' \
  'https://api.lipila.dev/api/v1/collections/card' \
  -H 'accept: application/json' \
  -H 'callbackUrl: https://lipila.io/callback' \
  -H 'x-api-key: Your_secret_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "260xxxxxxxxxx",
    "city": "lusaka",
    "country": "ZM",
    "address": "Matero plot number 23423",
    "zip": "10101",
    "email": "test@gmail.com"
  },
  "collectionRequest": {
    "referenceId": "43174606b87e", // Use this Id to check the transaction status
    "amount": 1,
    "narration": "test",
    "accountNumber": "260xxxxxxxxxx",
    "currency": "ZMW",
    "backUrl": "https://www.test.com/",
    "redirectUrl": "https://www.test.com/"
  }
}'

Example Successful Response

Below is a successful response from the above request.

HTTP Status Code	Description
200	SUCCESS

  {
  "currency": "ZMW",
  "amount": 1,
  "accountNumber": "test@gmail.com",
  "status": "Pending",
  "paymentType": "Card",
  "ipAddress": "::1",
  "cardRedirectionUrl": "https://secure.3gdirectpay.com/payv2.php?ID=7400B9C3-CB89-41E4-9C49-9B5031EE847A",
  "createdAt": "2026-02-05T10:01:16.568522+00:00",
  "referenceId": "12345678909876543345678", 
  "identifier": "LPLXC-20260205-100116-3102"
  }

INFO

You have successfully initiated a card payment but this is not the end. Your response should have a cardRedirectionUrl just like the above example. When you open this url you will be redirected to a page where you enter your card details. After you submit your card details you will receive confirmation from your bank to approve this payment. This will determine the status of your transaction. Make sure your card is either a master card or visa.

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, verify your keys
403	FORBIDDEN	Access denied to this resource, verify your keys
429	TOO MANY REQUESTS	Rate limit exceeded, slow down requests