M-Pesa Express (STK Push) API Guide

The M-Pesa Express API (STK/NI Push) initiates an online payment on behalf of a customer, providing a seamless payment experience for both businesses and customers. By integrating with this API, businesses can send a payment prompt to a customer’s phone, allowing them to authorize the payment by entering their M-PESA PIN. This eliminates the need to remember business paybill numbers or account numbers.

Endpoint Overview

• Method: POST
• URL: https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest
• Authentication: Requires an access token generated via the Authorization API.

Workflow

The Lipa na M-Pesa Express API works as follows:

1. The merchant sets the required parameters and sends the API request.
2. The API validates the request and returns an acknowledgment response.
3. An STK Push prompt is triggered to the customer’s M-PESA-registered phone number.
4. The customer authorizes the payment by entering their M-PESA PIN.
5. M-PESA processes the payment by:
   • Verifying the customer’s PIN.
   • Debiting the customer’s M-PESA account.
   • Crediting the merchant’s account.
6. M-PESA sends the result to the API Management system, which forwards it to the merchant’s callback URL.
7. The customer receives an SMS confirmation.

Request Setup

1. Generate an Access Token

To authenticate your request, first generate an access token using the Authorization API. Learn more about [Authorization API here].

2. Define the Request Body

In your request body, provide the following parameters in JSON format:

{
   "BusinessShortCode": "174379",
   "Password": "MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZTZiNzJhZGExZWQyYzkxOTIwMTYwMjE2MTY1NjI3",
   "Timestamp":"20160216165627",
   "TransactionType": "CustomerPayBillOnline",
   "Amount": "1",
   "PartyA":"254708920430",
   "PartyB":"174379",
   "PhoneNumber":"254708920430",
   "CallBackURL": "https://mydomain.com/path",
   "AccountReference":"Test",
   "TransactionDesc":"Test"
}

Request Parameter Description

Example Response

Upon successful request, the API will return the following response:

{
   "MerchantRequestID": "29115-34620561-1",
   "CheckoutRequestID": "ws_CO_191220191020363925",
   "ResponseCode": "0",
   "ResponseDescription": "Success. Request accepted for processing",
   "CustomerMessage": "Success. Request accepted for processing"
}

Response Parameters

Callback Result

After the transaction is processed, M-PESA will send a callback with the result to the specified CallBackURL.

Successful Result Body

{
   "Body": {
      "stkCallback": {
         "MerchantRequestID": "29115-34620561-1",
         "CheckoutRequestID": "ws_CO_011120241020363925",
         "ResultCode": 0,
         "ResultDesc": "The service request is processed successfully.",
         "CallbackMetadata": {
            "Item": [
               {"Name": "Amount", "Value": 1.00},
               {"Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV"},
               {"Name": "TransactionDate", "Value": 20241101102115},
               {"Name": "PhoneNumber", "Value": 254708920430}
            ]
         }
      }
   }
}

Callback Result Description

Unsuccessful Result Body

If the transaction fails, the callback result will contain the error details, as shown below:

{
   "Body": {
      "stkCallback": {
         "MerchantRequestID": "29115-34620561-1",
         "CheckoutRequestID": "ws_CO_191220191020363925",
         "ResultCode": 1032,
         "ResultDesc": "Request canceled by user."
      }
   }
}

Error codes Summary

In this example, ResultCode indicates an error (e.g., 1032 means "Request canceled by user").

For any suggestions, comments, or issues encountered during implementation, please let us know to help improve this API guide.

Happy Coding