Lipisha Instant Transaction Notification (IPN)


Processing Callbacks


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:



How to Process a Transaction Callback in 2 Easy Steps

  1. Initiate - Firstly, a HTTP POST will be made to your Callback URL with the transaction. Your application MUST then synchronously return a JSON to accept or reject the transaction.
  2. Acknowledge - Finally, a HTTP POST will be made asynchronously to your Callback URL to confirm the transaction.
NB: 0. Prepare - This is a custom pre-processing step for some types of integrations. The documentation is customized and provided separately based on the merchant's specifications.

Endpoint

https://example.com/payments/lipisha/notifications.php YOUR CALLBACK URL

1. INITIATE

Request POST application/x-www-form-urlencoded

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
  • Payout
  • Reversal
  • Settlement
Payment
transaction_country Country of origin of the transaction. In 2 letter international ISO format. Options are:
  • KE (Kenya)
  • RW (Rwanda)
  • UG (Uganda)
  • TZ (Tanzania)
KE
transaction_method Method used to carry out a transaction. Varies according to transaction_type and transaction_country.
For Payments:
Kenya
  • Paybill (M-Pesa)
  • Paybill (Equitel)
  • Paybill (Airtel Money)
  • Buy Goods (M-Pesa)
Rwanda
  • Paybill (MTN Money)
  • Paybill (Tigo Cash)
Uganda
  • Paybill (MTN Money)
  • Paybill (Airtel Money)
Tanzania
  • Paybill (Vodacom M-Pesa)

For Payouts:
Kenya
  • Bulkpay (M-Pesa)
  • Bulkpay (Airtel Money)
Uganda
  • Bulkpay (Mtn Money)
  • Bulkpay (Airtel Money)
Ghana
  • Bulkpay (Mtn Money)
  • Bulkpay (Airtel Money)
  • Bulkpay (Vodafone)
  • Bulkpay (Expresso)
  • Bulkpay (Glo Cash)
  • Bulkpay (Tigo Cash)

For Settlements:
Kenya
  • Bank (SWIFT)
International
  • Bank (SWIFT)
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 (Kenya Shillings)
  • RWF (Rwanda Francs)
  • UGX (Uganda Shillings)
  • TZS (Tanzania Shillings)
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
  • Dedicated
Shared
transaction_account Number of the transaction account. 000075
transaction_account_number Similar to transaction_account 000075
transaction_account_name Name of the transaction account. Test Account
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_status Status of a transaction. Options are:
  • Completed
  • Failed
Completed

Response application/json

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 (Valid transaction)
  • 002 (Invalid transaction)
001
transaction_status Status of the transaction. Options are:
  • SUCCESS
  • FAIL
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:
  • ACCEPT
For FAIL:
  • ACCEPT
  • REJECT

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
  • Paybill (M-Pesa)
  • Paybill (Equitel)
  • Buy Goods (M-Pesa)
Rwanda
  • Paybill (MTN Money)
  • Paybill (Tigo Cash)
Uganda
  • Paybill (MTN Money)
Tanzania
  • Paybill (Vodacom M-Pesa)
ACCEPT
transaction_status_reason Reason for the status. Varies according to transaction_status

For SUCCESS:
  • VALID_TRANSACTION
For FAIL:
  • INVALID_TRANSACTION
  • INVALID_TRANSACTION_MOBILE
  • INVALID_TRANSACTION_AMOUNT
  • INVALID_TRANSACTION_NAME
  • INVALID_TRANSACTION_PAYBILL
  • INVALID_TRANSACTION_ACCOUNT_NUMBER
  • INVALID_TRANSACTION_MERCHANT_REFERENCE
  • INVALID_TRANSACTION_METHOD
  • INVALID_TRANSACTION_EMAIL
  • INVALID_TRANSACTION_DATE
  • FRAUD_TRANSACTION
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.

Example Responses
{
      "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"
}

2. ACKNOWLEDGE POST application/x-www-form-urlencoded

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 (Valid transaction)
  • 002 (Invalid transaction)
  • 003 (Timeout transaction)
001
transaction_status Status of the response. Options are:
  • SUCCESS
  • FAIL
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
  • REJECT
ACCEPT
transaction_status_reason Reason for the status response. Options are:
  • VALID_TRANSACTION
  • INVALID_TRANSACTION
  • INVALID_TRANSACTION_MOBILE
  • INVALID_TRANSACTION_AMOUNT
  • INVALID_TRANSACTION_NAME
  • INVALID_TRANSACTION_PAYBILL
  • INVALID_TRANSACTION_ACCOUNT_NUMBER
  • INVALID_TRANSACTION_MERCHANT_REFERENCE
  • INVALID_TRANSACTION_METHOD
  • INVALID_TRANSACTION_EMAIL
  • INVALID_TRANSACTION_DATE
  • FRAUD_TRANSACTION
  • TIMEOUT_TRANSACTION
VALID_TRANSACTION


Examples

<?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 
    }           
}

Fork me on GitHub