The Lipa na M-Pesa (LNM) API is a C2B API designed to utilize the new feature introduced by Safaricom known as STK Push. This feature allows the transaction initiation to be moved from the paying customer’s side to the payee Organization’s side. This eliminates the hustle of having to remember business paybill numbers and account numbers for customers, and allows them to simply confirm the current transaction by entering their M-Pesa PIN on their mobile phone. This is done via the STK Push prompt which appears on a customer’s phone that asks them to enter their PIN. For businesses, this API enables them to preset all the correct info in the payment request and greatly reduce chances of wrong payments being sent to their systems. It is a C2B transaction, but with the initiator being the organization instead of the customer. Here, the organization has the option of presetting all required variables in the request before sending the request, thus this API has no Validation-Confirmation process of it’s own unlike the previous C2B API (but is still affected by any previous C2B integrations done on the shortcode being used in the request, especially Validation/Confirmation). It’s process is explained below together with a flow chart:

1. The Business sets the data in the request and sends it
2. The API receives the request and validates it internally first, then sends you an acknowledgement response.
3. The API then sends an STK Push request to the target customer’s mobile phone. The customer’s phone has to be online and unlocked to receive the request.
4. The customer confirms the payment amount via the message displayed on-screen, then either enters the PIN or cancels the request accordingly.
5. The API receives the customer’s response. If the response is a negative, it cancels the transaction and sends a corresponding callback to the initiating 3rd party via the predefined callback URL in the initial request, with the info on why the transaction was cancelled. The possible negative responses could be due to the following scenarios:
   • An invalid PIN entered by the customer
   • Timeout due to customer not entering the PIN within a given time period (usually 1 min 30 secs)
   • The customer’s SIM card not having the STK applet on it
   • A literal request cancellation by the user on their phone
   • Another STK transaction is already underway on the customer’s phone (no more than one request can be processed at the same time on the same phone)
6. If the PIN is correct, it means the customer accepted the request. The API forwards the transaction to M-Pesa.
7. M-Pesa automatically processes the request, then sends the response back to the API system which then forwards it to you via the callback URL specified in your initial request. Here, the callback can also either be a success or failure, just like a normal C2B transaction.
8. There are no repeat calls for failed callbacks, thus if the API is unable to send the callback to you, you have the Transaction Status Query API to confirm the status of the request, or also confirm via the M-Pesa Org. portal.

For this API, you shall need your actual production line to test the API. Your line must have the STK applet installed (you can update by dialing *234*1*6# on your handset (as of the day of writing of this tutorial. If the update does not work, or your physical SIM card is more than 3 years old, consider replacing it), and you must be registered on M-Pesa. The funds utilized are automatically refunded at midnight. I suggest using values as low as 1 – 10 shillings to perform your transactions to lengthen the number of tries you make. Also beware, the API does not allow one to perform more than 5 consecutive STK requests without completing them. This is marked as phishing, and will cause your line to be blocked from making any more STK requests over 24 hours.

The LNM request takes the format below:

// URL
[POST] https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest

// HEADERS
Host: sandbox.safaricom.co.ke
Authorization: Bearer [access_token]
Content-Type: application/json

// BODY
{
	"BusinessShortCode": "174379",
	"Password": "MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZTZiNzJhZGExZWQyYzkxOTIwMTkxMTI0MTkyMjEx",
	"Timestamp": "20191124192211",
	"TransactionType": "[Transaction Type]",
	"Amount": "1000",
	"PartyA": "254708374149",
	"PartyB": "174379",
	"PhoneNumber": "254708374149",
	"CallBackURL": "https://peternjeru.co.ke/safdaraja/api/callback.php"
	"AccountReference": "account",
	"TransactionDesc": "test" ,
}

Some definitions

BusinessShortCode

This is the shortcode of the organization initiating the request and expecting the payment.

Password

This is the Base64-encoded value of the concatenation of the Shortcode + LNM Passkey + Timestamp, e.g. given the test values above, and using a timestamp of 20191124192211, the encoded password will be

MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZTZiNzJhZGExZWQyYzkxOTIwMTkxMTI0MTkyMjEx

You can use this site to confirm your encoding.

Timestamp

This is the same Timestamp used in the encoding above, in the format YYYMMDDHHmmss.

TransactionType

The type of transaction being performed. These are the same values as the C2B command IDs (CustomerPayBillOnline and CustomerBuyGoodsOnline) and the same rules apply here. For now, only CustomerPayBillOnline is supported.

Amount

Self explanatory.

PartyA

The Debit party of the transaction/the party paying out in the transaction, hereby the phone number of the customer.

PartyB

The credit party of the transaction/the party being paid in the transaction, hereby being the shortcode of the organization. This is the same value as the Business Shortcode

PhoneNumber

Same as PartyA.

CallBackURL

This is the endpoint where you want the results of the transaction delivered. Same rules for Register URL API callbacks apply

AccountReference

This is the value the customer would have put as the account number on their phone if they had performed the transaction via phone.

TransactionDesc

Short description of the transaction. Optional, but element must be present.

After sending a successful transaction, you can expect a response in the below format:

{
    "MerchantRequestID": "25353-1377561-4",
    "CheckoutRequestID": "ws_CO_26032018185226297",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing",
    "CustomerMessage": "Success. Request accepted for processing"
}

Note the ResponseCode. The value 0 (zero) means the request was accepted successfully. Any other value means there was an error validating your request. Confirm the error on the ResponseDescription and fix it. The CheckoutRequestID is your unique request ID and can be used later for the LNM Transaction Query API.

After sending the callback, and assuming a customer has accepted your request and responded to it, a successful callback will have the structure below:

{
	"Body": 
	{
		"stkCallback": 
		{
			"MerchantRequestID": "21605-295434-4",
			"CheckoutRequestID": "ws_CO_04112017184930742",
			"ResultCode": 0,
			"ResultDesc": "The service request is processed successfully.",
			"CallbackMetadata": 
			{
				"Item": 
				[
					{
						"Name": "Amount",
						"Value": 1
					},
					{
						"Name": "MpesaReceiptNumber",
						"Value": "LK451H35OP"
					},
					{
						"Name": "Balance"
					},
					{
						"Name": "TransactionDate",
						"Value": 20171104184944
					},
					{
						"Name": "PhoneNumber",
						"Value": 254727894083
					}
				]
			}
		}
	}
}

I believe all elements there are already known. I will shift your attention to the ResultCode,which shows the status of the request. The 0 (zero) means a success as usual, anything else will be an error whose description is defined in ResultDesc. The M-Pesa Receipt Number is your unique identifier of the transaction on M-Pesa, and can be used with the Sandbox Transaction Query API.