M-Pesa Express (STK Push) API Guide

The M-Pesa Express API, also known as the STK/NI Push API, enables businesses to initiate online payments on behalf of customers, providing a seamless payment experience. 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. The API uses a POST method and requires an access token generated via the Authorization API. The workflow involves the merchant setting the required parameters and sending the API request, which is then validated and triggers an STK Push prompt to the customer's phone. The customer authorizes the payment by entering their M-PESA PIN, and M-PESA processes the payment by verifying the PIN, debiting the customer's account, and crediting the merchant's account. The API request body requires parameters such as BusinessShortCode, Password, Timestamp, TransactionType, Amount, PartyA, PartyB, PhoneNumber, CallBackURL, AccountReference, and TransactionDesc. The API returns a response with parameters such as MerchantRequestID, CheckoutRequestID, ResponseCode, ResponseDescription, and CustomerMessage. After the transaction is processed, M-PESA sends a callback with the result to the specified CallBackURL. The callback result includes parameters such as MerchantRequestID, CheckoutRequestID, ResultCode, ResultDesc, and CallbackMetadata. The CallbackMetadata contains additional transaction details such as Amount, MpesaReceiptNumber, TransactionDate, and PhoneNumber. Error codes are also provided to help diagnose and resolve issues encountered during implementation. These error codes include DS timeout, issue with push request, general push request error, user canceled the request, insufficient balance, invalid initiator information, transaction expired, and subscriber lock error.