Callback

Lipila uses Callbacks to notify your system in real-time of the status of your transactions.
Instead of polling our APIs, your application will only receive a callback when a transaction is either successful or has failed.

Callback Response Properties 1.0.0

The table below describes the properties you will find in the Callback response

Property	Type	Description
referenceId	string (GUID)	A unique identifier generated by Lipila for the transaction. You can use this to look up the transaction in Lipila’s API or dashboard.
currency	string	The currency used for the transaction, e.g. ZMW, USD, etc.
amount	decimal	The exact amount that was charged or collected.
accountNumber	string	The customer’s account number or mobile wallet number used to make the payment.
status	string	The final status of the transaction. Possible values include: • Successful — The payment was processed successfully. • Failed — The payment could not be completed.
paymentType	string	The payment method used by the customer, such as Card, AirtelMoney, MTNMoney, or Bank.
type	string	The transaction category. For example: • Collection — Money collected from a customer. • Disbursement — Money sent to a beneficiary.
ipAddress	string	The IP address of the device or source that initiated the transaction.
identifier	string	A unique internal identifier provided by your system when the transaction was created. This helps you correlate Lipila’s Callback with your internal records.
message	string	A descriptive message providing more context about the transaction status. Example: "Payment completed successfully."
externalId	string (optional)	The transaction ID returned by the MNOs (MTN, ZAMTEL, AIRTEL). Useful for reconciliation.

Example Callback Response

When a payment succeeds or fails, Lipila sends a payload like this:

{
  "referenceId": "b4c9a8f1-7c4d-4b3e-bc8a-5d9e2b15f7a1",
  "currency": "ZMW",
  "amount": 1.75,
  "accountNumber": "260xxxxxxxxxx",
  "status": "Successful",
  "paymentType": "Card",
  "type": "Collection",
  "ipAddress": "102.89.34.10",
  "identifier": "TXN123456789",
  "message": "Payment completed successfully.",
  "externalId": "MP250000987654321"
}