Once you register your Callback URL and subscribe to notifications, any transaction done e.g Payment, Payout, Reversal, Settlement, will automatically trigger an instant transaction notification to your application:
https://example.com/payments/lipisha/notifications.php YOUR CALLBACK URL
When a transaction is received, we will first send an Initiate via HTTP POST to your application's Callback URL.
| Parameter | Description | Example |
|---|---|---|
| api_key | Your Lipisha API key. | 3aa67677e8bf1d4c8fe886a38c03a860 |
| api_signature | Your Lipisha API signature. | SYetmwsNnb5bwaZRyeQKhZNNkCoEx+5x= |
| api_version | Version of the API | 2.0.0 |
| api_type | Type of handshake or callback | Initiate |
| transaction | Unique transaction idenitifier. | CU79AW109D |
| transaction_reference | Similar to transaction | CU79AW109D |
| transaction_type | Type of transaction. Options are:
|
Payment |
| transaction_country |
Country of origin of the transaction. In 2 letter international ISO format. Options are:
|
KE |
| transaction_method | Method used to carry out a transaction. Varies according to transaction_type and transaction_country.
For Payments: Kenya
For Payouts: Kenya
For Settlements: Kenya
|
Paybill (M-Pesa) |
| transaction_date | Date and time of the transaction. In the format: YYYY-MM-DD HH:mm:ss |
2013-02-02 12:30:45 |
| transaction_currency |
Currency of the transaction. In 3 letter international ISO format. Options are:
|
KES |
| transaction_amount | Value of the transaction. | 100.00 |
| transaction_paybill | Paybill, business number, till number, merchant nickname, or merchant number used for the transaction | 961700 |
| transaction_paybill_type |
Type of the Paybill. Options are:
|
Shared |
| transaction_account | Number of the transaction account. | 000075 |
| transaction_account_number | Similar to transaction_account | 000075 |
| transaction_account_keyword | An alias to the transaction_account_number. User friendly alternative made of alphabets and used instead of account number mainly in shared paybills. | LOAN |
| transaction_account_name | Name of the transaction account. | Test Account |
| transaction_account_balance | Balance or Float available on the transaction account. | 100.00 |
| transaction_merchant_reference | Reference a person or entity used when executing a transaction. E.g. invoice, receipt, member number | LS0009 |
| transaction_name | Name of the person or entity that made a transaction. | JOHN JANE DOE |
| transaction_mobile | Mobile number of the person or entity that made a transaction. | 254722002222 |
| transaction_email | Email of the person or entity that made a transaction. | test@test.com |
| transaction_code | Unique code returned by the mobile money network or financial service provider E.g the M-Pesa confirmation code | CU79AW109D |
| transaction_gateway_code | Code returned by other intermediary platforms between mobile money network or financial service provider and Lipisha e.g third party partner. Available only for some networks and mainly for dedicated business numbers. | 1234567900001234 |
| transaction_status | Status of a transaction. Options are:
|
Completed |
On receiving the Initiate HTTP POST, your application should respond synchronously with a Receipt via JSON.
| Parameter | Description | Example |
|---|---|---|
| api_key | Your Lipisha API key. | 3aa67677e8bf1d4c8fe886a38c03a860 |
| api_signature | Your Lipisha API signature. | SYetmwsNnKhZNNkCoEx+5x= |
| api_version | Version of the API | 2.0.0 |
| api_type | Type of handshake or callback | Receipt |
| transaction | Unique transaction idenitifier. | CU79AW109D |
| transaction_reference | Similar to transaction | CU79AW109D |
| transaction_status_code | Status code based on nature of transaction. Options are:
|
001 |
| transaction_status | Status of the transaction. Options are:
|
SUCCESS |
| transaction_status_description | Description of the status. | Transaction received successfully. |
| transaction_status_action |
Action to carry out on the transaction based on status. Varies according to transaction_status.
Default action is ACCEPT if not specified. Transactions which are valid are accepted and funds processed. Transactions which are invalid can either be accepted and funds processed or rejected before funds are processed. For SUCCESS:
REJECT is not supported for all transactions or by all providers. Varies according to transaction_type, transaction_country and transaction_method. Currently only supported for Payments in: Kenya
Shared paybill transactions are automatically accepted regardless of status action provided. |
ACCEPT |
| transaction_status_reason |
Reason for the status. Varies according to transaction_status
For SUCCESS:
|
VALID_TRANSACTION |
| transaction_custom_sms | Custom SMS to replace the default transaction SMS. *Feature is only available for merchants with branded SMS sender id. |
Dear JOHN JANE DOE, your payment of KES 100.00 via CU79AW109D was received. |
{
"api_key": "3aa67677e8bf1d4c8fe886a38c03a860",
"api_signature": "SYetmwsNnb5bwaZRyeQKhZNNkCoEx+5x=",
"api_version": "2.0.0",
"api_type": "Receipt",
"transaction_reference": "CU79AW109",
"transaction_status_code": "001",
"transaction_status": "SUCCESS",
"transaction_status_description": "Transaction received successfully.",
"transaction_status_action": "ACCEPT",
"transaction_status_reason": "VALID_TRANSACTION",
"transaction_custom_sms": "Dear JOHN JANE DOE, your payment of KES 100.00 via CU79AW109D was received."
}{
"api_key": "3aa67677e8bf1d4c8fe886a38c03a860",
"api_signature": "SYetmwsNnb5bwaZRyeQKhZNNkCoEx+5x=",
"api_version": "2.0.0",
"api_type": "Receipt",
"transaction_reference": "CU79AW109",
"transaction_status_code": "002",
"transaction_status": "FAIL",
"transaction_status_description": "Transaction has a problem but we accept.",
"transaction_status_action": "ACCEPT",
"transaction_status_reason": "INVALID_TRANSACTION"
}{
"api_key": "3aa67677e8bf1d4c8fe886a38c03a860",
"api_signature": "SYetmwsNnb5bwaZRyeQKhZNNkCoEx+5x=",
"api_version": "2.0.0",
"api_type": "Receipt",
"transaction_reference": "CU79AW109",
"transaction_status_code": "002",
"transaction_status": "FAIL",
"transaction_status_description": "Transaction has a problem and we reject.",
"transaction_status_action": "REJECT",
"transaction_status_reason": "INVALID_TRANSACTION_ACCOUNT_NUMBER"
}On receiving your Receipt JSON, we will respond asynchronously with an Acknowledge via HTTP POST.
| Parameter | Description | Example |
|---|---|---|
| api_key | Your Lipisha API key. | 3aa67677e8bf1d4c8fe886a38c03a860 |
| api_signature | Your Lipisha API signature. | SYetmwsNnKhZNNkCoEx+5x= |
| api_version | Version of the API | 2.0.0 |
| api_type | Type of handshake or callback | Acknowledge |
| transaction | Unique transaction idenitifier. | CU79AW109D |
| transaction_reference | Similar to transaction | CU79AW109D |
| transaction_status_code | Status code of the response. Options are:
|
001 |
| transaction_status | Status of the response. Options are:
|
SUCCESS |
| transaction_status_description | Description of the response. | Transaction processed successfully. |
| transaction_status_action |
Action carried out on receiving the Initiate callback. Options are:
|
ACCEPT |
| transaction_status_reason |
Reason for the status response. Options are:
|
VALID_TRANSACTION |
<?php
// Check if Lipisha ITN server has made a callback
if(isset($_POST))
{
// Your API details for authentication
$api_key = "Your API key"; // Check under Settings->API in Lipisha dashboard
$api_signature = "Your API Signature"; // Check under Settings->API in Lipisha dashboard
// Confirm if authentication details are genuine else log a fraud attempt
if (($_POST["api_key"] == $api_key) && ($_POST["api_signature"] == $api_signature))
{
// Process Initiate
if($_POST["api_type"] == "Initiate")
{
// Extract transaction details
$country = $_POST["transaction_country"];
$type = $_POST["transaction_type"];
$method = $_POST["transaction_method"];
$date = $_POST["transaction_date"];
$currency = $_POST["transaction_currency"];
$amount = $_POST["transaction_amount"];
$name = $_POST["transaction_name"];
$mobile = $_POST["transaction_mobile"];
$email = $_POST["transaction_email"];
$paybill = $_POST["transaction_paybill"];
$paybill_type = $_POST["transaction_paybill_type"];
$account_number = $_POST["transaction_account_number"];
$account_name = $_POST["transaction_account_name"];
$reference = $_POST["transaction_reference"];
$merchant_reference = $_POST["transaction_merchant_reference"];
$code = $_POST["transaction_code"];
$status = $_POST["transaction_status"];
// Perform action e.g update order/invoice as paid, save to database or log
process_initiate($_POST); // replace with your own actions
// Acknowledge API call
$response= array();
$response["api_key"] = $_POST["api_key"];
$response["api_signature"] = $_POST["api_signature"];
$response["api_version"] = $_POST["api_version"];
$response["api_type"] = "Receipt";
$response["transaction_reference"] = $_POST["transaction_reference"];
$response["transaction_status_code"] = "001";
$response["transaction_status"] = "SUCCESS";
$response["transaction_status_description"] = "Transaction received successfully.";
$response["transaction_status_action"] = "ACCEPT";
$response["transaction_status_reason"] = "VALID_TRANSACTION";
$response["transaction_custom_sms"] = "Dear $name, your payment of $currency $amount via $code was received."; // Customize SMS
header("Content-Type: application/json");
echo json_encode($response); // This should be the only printed output of this page to prevent header session already sent error occuring
}
// Process Acknowledge
if($_POST["api_type"] == "Acknowledge")
{
// Perform action e.g update your transaction table as confirmed
process_acknowledge($_POST); // replace with your own actions
}
}
else
{
// Log attempted fraud if api credentials are wrong
process_fraud($_POST); // replace with your own actions
}
}