This document outlines APIs required for integrating with the Safaricom M-Pesa service, the purpose of each API, the type of sample data to be sent, and how to determine the success or failure of transactions. It also covers error codes and the structure of REST API responses.
\nThere are URLs required from the client which include confirmation and validation URL.
1.Confirmation URL
Confirmation url is used to receive transaction callback.
Confirmation results posted on your URL will have the structure below.
2.Validation URL
\nValidation request is received by clients who have external validation enabled on their PayBill or BuyGoods and require validating a payment before M-PESA completes the transaction. You will receive validation request to validate on your validation URL.
\nThe valiation results posted on your URL after payment will have the structure below.
\nValidation Response
After receiving the validation request, you are required to process it and respond to the API call and inform us whether to accept or reject the payment. We send the response we receive to M-PESA.
To accept. you send the JSON making sure the value of the ResultCode is 0(zero), but the value of ResultDesc is Accepted.
To reject a transaction, send the same JSON above, but with the ResultCode set as C2B00011. BUT NOT 0. The ResultDesc should be set as Rejected as shown below
\nFailed STK Callback
\nSuccesfull STK Callback
\nFailed B2C Callback
\nSuccesful B2C Callback
\nThis API is used in initiating an STK push
\n","urlObject":{"protocol":"https","path":["api","v1","payments","initiateSTKpush"],"host":["payments","muva","tech"],"query":[],"variable":[]}},"response":[{"id":"2082fdda-da64-408d-947d-a10549d7a7af","name":"initiate STK push","originalRequest":{"method":"POST","header":[{"key":"Origin","value":"https://payments.muva.tech","type":"text"}],"body":{"mode":"raw","raw":"{\n \"phoneNumber\": \"0715316525\",\n \"amount\":\"10\",\n \"transactionReference\": \"TXN-17337398003e760-06IMB51122M1122\"\n}\n","options":{"raw":{"language":"json"}}},"url":"{{produrl}}/api/v1/payments/initiateSTKpush"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.24.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Mon, 24 Feb 2025 11:22:51 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"}],"cookie":[],"responseTime":null,"body":"{\n \"responseCode\": 0,\n \"transactionReference\": \"TXN-17337398003e760-06IMB51122M1122\",\n \"responseMessage\": \"Success. Request accepted for processing\"\n}"}],"_postman_id":"6f5f1e4b-a4a5-40a8-8d50-d57e7aca1660"},{"name":"initiateB2C","id":"14cc3602-966f-43aa-ad2d-6c897a58ba3b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This API is used in initiating payment to a client from the organization
\n","urlObject":{"protocol":"https","path":["api","v1","payments","initiateB2C"],"host":["payments","muva","tech"],"query":[],"variable":[]}},"response":[{"id":"8d497b2c-fda9-46f7-af62-b43224dfbda1","name":"initiateB2C","originalRequest":{"method":"POST","header":[{"key":"Origin","value":"https://payments.muva.tech","type":"text"}],"body":{"mode":"raw","raw":"{\n \"phoneNumber\": \"0715316525\",\n \"amount\": \"10\",\n \"transactionReference\": \"TXN-1733318510934-MHK7Rxq\"\n}","options":{"raw":{"language":"json"}}},"url":"https://payments.muva.tech/api/v1/payments/initiateB2C"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.24.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Mon, 24 Feb 2025 11:35:09 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"}],"cookie":[],"responseTime":null,"body":"{\n \"responseCode\": 0,\n \"transactionReference\": \"TXN-1733318510934-MHK7Rxq\",\n \"responseMessage\": \"Request Accepted and Queued Successfully\"\n}"}],"_postman_id":"14cc3602-966f-43aa-ad2d-6c897a58ba3b"}]}