M-Pesa Express

Safaricom's name for this is Lipa na M-Pesa Online, more commonly referred to (including by Safaricom's own portal navigation) as M-Pesa Express or STK Push. It is a merchant-initiated C2B transaction: instead of the customer dialing into a Pay Bill themselves, the merchant triggers a payment prompt directly on the customer's phone.

M-Pesa Express Simulate (STK Push)Copy Anchor Link

Endpoint

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

How it worksCopy Anchor Link

1. The merchant sends a request with the transaction details.
2. Daraja validates the request and acknowledges it.
3. A prompt is pushed to the customer's M-PESA-registered phone.
4. The customer enters their M-PESA PIN to authorize.
5. M-PESA validates the PIN, debits the customer, and credits the merchant.
6. The result is posted to the merchant's CallBackURL.
7. The customer receives an SMS confirmation.

PrerequisitesCopy Anchor Link

• Daraja account and sandbox app, with Consumer Key and Consumer Secret.
• A passkey to encrypt the Password field. On sandbox this is provided on the Test Credentials page; in production it's emailed after go-live.
• For go-live: a live Pay Bill/Till with Business Admin/Manager operators created.

RequestCopy Anchor Link

{
  "BusinessShortCode": 174379,
  "Password": "MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZTZiNzJhZGExZWQyYzkxOTIwMjEwNjI4MDkyNDA4",
  "Timestamp": "20210628092408",
  "TransactionType": "CustomerPayBillOnline",
  "Amount": "1",
  "PartyA": "254722000000",
  "PartyB": "174379",
  "PhoneNumber": "254722111111",
  "CallBackURL": "https://mydomain.com/path",
  "AccountReference": "accountref",
  "TransactionDesc": "txndesc"
}

ResponseCopy Anchor Link

{
  "MerchantRequestID": "2654-4b64-97ff-b827b542881d3130",
  "CheckoutRequestID": "ws_CO_1007202409152617172396192",
  "ResponseCode": "0",
  "ResponseDescription": "Success. Request accepted for processing",
  "CustomerMessage": "Success. Request accepted for processing"
}

Callback payloadCopy Anchor Link

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

Error codesCopy Anchor Link

M-Pesa Express QueryCopy Anchor Link

Checks the status of an already-submitted STK Push.

Endpoint

https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query

RequestCopy Anchor Link

{
  "BusinessShortCode": "174379",
  "Password": "MTc0Mzc5YmZiMjc5TliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZTZiNzJhZGExZWQyYzkxOTIwMTYwMjE2MTY1NjI3",
  "Timestamp": "20160216165627",
  "CheckoutRequestID": "ws_CO_260520211133524545"
}

ResponseCopy Anchor Link

{
  "ResponseCode": "0",
  "ResponseDescription": "The service request has been accepted successfully",
  "MerchantRequestID": "22205-34066-1",
  "CheckoutRequestID": "ws_CO_13012021093521236557",
  "ResultCode": "0",
  "ResultDesc": "The service request is processed successfully."
}

ResultDesc 1032 maps to "Request canceled by the user"; 0 maps to success. Beyond those two, Safaricom's query documentation doesn't enumerate the full result code list separately, since it overlaps with the push callback's codes above.

TestingCopy Anchor Link

Daraja Simulator: create a test app with the M-Pesa Express (Lipa na M-Pesa) product attached; the simulator auto-fills credentials and test data.

Postman: token from https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials, then call the push or query endpoint above.

Go LiveCopy Anchor Link

See Organization Portal & Go Live for creating the admin/manager operators. On the portal's Go Live tab, submit your live short code, organization name (Safaricom asks that special characters be stripped from it), and M-PESA admin/manager username (case-sensitive). Production endpoints and production Consumer Key/Secret follow by email.

FAQsCopy Anchor Link