1. STK Push Overview

Objective: Understand how the STK Push process facilitates seamless payment initiation.

• What is an STK Push?
  STK Push (Sim Toolkit Push) is a payment request sent to a user’s phone via Mpesa, prompting them to enter their PIN to approve the transaction.

• Why Use STK Push?
  It provides a secure and user-friendly way to collect payments, especially in e-commerce, donations, or service payments.

• Workflow:

  1. The system sends a payment request to the user’s phone.
  2. The user confirms the transaction by entering their PIN.
  3. The response indicates the success or failure of the request.

2. API Endpoint

Objective: Learn the endpoint used to initiate STK Push transactions.

• STK Push Endpoint:

  https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest
  

• HTTP Method:
  Use the POST method to send data.

3. Required Parameters

Objective: Familiarize yourself with the necessary parameters for an STK Push request.

Below is a list of critical parameters and their roles:

• BusinessShortCode:
  A unique short code (till number) provided by Mpesa for your business.
  Example: 174379 (for testing).

• Password:
  A base64-encoded string of the BusinessShortCode, Passkey, and Timestamp.

  • Formula:

    Password = Base64Encode(BusinessShortCode + Passkey + Timestamp)
    

  • Example in PHP:

    $password = base64_encode($businessShortCode . $passkey . $timestamp);
    

• Timestamp:
  A string representing the current time in the format YYYYMMDDHHMMSS.

  • Example in Node.js:

    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
    

• Amount:
  The transaction amount in Kenyan Shillings (KSh).

• PartyA:
  The phone number of the user initiating the payment.

• PartyB:
  The payee’s business number (e.g., till or paybill number).

• PhoneNumber:
  The same as PartyA—the phone number to receive the STK Push request.

• CallbackURL:
  A URL where Mpesa will send the transaction response.

• TransactionDesc:
  A brief description of the transaction (e.g., “Payment for Order #123”).

4. Code Implementation

Objective: Implement the STK Push request in code.

• Example in PHP:

  function initiateSTKPush($accessToken, $shortCode, $passkey, $phoneNumber, $amount, $callbackUrl) {
      $timestamp = date('YmdHis');
      $password = base64_encode($shortCode . $passkey . $timestamp);
  
      $url = "https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest";
  
      $curl = curl_init();
      curl_setopt($curl, CURLOPT_URL, $url);
      curl_setopt($curl, CURLOPT_HTTPHEADER, [
          "Authorization: Bearer $accessToken",
          "Content-Type: application/json"
      ]);
      curl_setopt($curl, CURLOPT_POST, true);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  
      $data = [
          "BusinessShortCode" => $shortCode,
          "Password" => $password,
          "Timestamp" => $timestamp,
          "TransactionType" => "CustomerPayBillOnline",
          "Amount" => $amount,
          "PartyA" => $phoneNumber,
          "PartyB" => $shortCode,
          "PhoneNumber" => $phoneNumber,
          "CallBackURL" => $callbackUrl,
          "AccountReference" => "Order123",
          "TransactionDesc" => "Payment for Order123"
      ];
  
      curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
  
      $response = curl_exec($curl);
      curl_close($curl);
  
      return $response;
  }
  

5. Handling API Response

Objective: Parse and handle the response from the STK Push API.

• Successful Request:
  A successful request will return a JSON response similar to the following:

  {
      "MerchantRequestID": "12345",
      "CheckoutRequestID": "67890",
      "ResponseCode": "0",
      "ResponseDescription": "Success. Request accepted for processing",
      "CustomerMessage": "Success. Request accepted for processing"
  }
  

  • ResponseCode: "0" indicates success.

• Error Scenarios:

  • Invalid Phone Number: Check the format and ensure it starts with 254.
  • Insufficient Balance: The user may not have enough funds for the transaction.

• Log Responses:
  Store both successful and failed responses for troubleshooting and analytics.

6. Testing STK Push

Objective: Verify the STK Push functionality in a test environment.

• Using Postman:

  1. Create a new POST request.
  2. Set the URL to the STK Push endpoint.
  3. Add headers:
     • Authorization: Bearer AccessToken
     • Content-Type: application/json
  4. Add the required parameters to the body in JSON format.
  5. Click Send and monitor the response.

• On the Phone:

  • If successful, you will receive an Mpesa pop-up on the test number to approve the payment.