Instructions to using the Vitumob Mpesa API

vm_mpesa_api_readme.md

To make an MPESA DARAJA request

1) Get the access token

GET https://vitumob-prod.appspot.com/payments/mpesa/token

Note: No additional parameters required

Response:

{
    "access_token": "dbeiaDd3YnAA6QdTt29ASkDTLuDq",
    "expires_in": "3599"
}

or this, if it's been stored in the session or DB

{
    "access_token": "dbeiaDd3YnAA6QdTt29ASkDTLuDq",
    "expiring_time": 1544450311,
    "expires_in": 3599,
    "updated_at": "2018-12-10T12:58:32.197229Z"
}

Always try request for an access_token before making the payment request, the backend will always send you the most recent access_token token. If it's expired, the backend also automatically updates it.

2) Make the MPESA STK PUSH request

POST https://vitumob-prod.appspot.com/payments/mpesa/payment/push/request

Headers:

'Authorization': '{access_token}'

Request body:

{
  "order": {
    "order_id": "1234567891",
    "user_phone_number": "254723123123",
    "amount": "12341"
  }
}

Response status code: 400

Response if no access token is provided:

{ "error": "Access token not provided" }

Response status code: 404

Response if your access token is provided but expired:

{
    "order_meta_data": {
        "order_id": "...43146956",
        "user_phone_number": "254723001575",
        "amount": "48744"
    },
    "status_code": 404,
    "daraja_error": {
        "errorCode": "404.001.03",
        "errorMessage": "Invalid Access Token",
        "requestId": "11209-2554107-1"
    }
}

Successful stk push response:

The CheckoutRequestID is the unique order_id from mpesa daraja

{
    "payment_id": "ws_CO_DMZ_215482558_10122018133312795",
    "user_id": "Nlqzi4hObdfLW8Tsaokng6fRtzb2",
    "order_id": "4787246431469568",
    "phone_no": "254723001575",
    "daraja_response": {
        "CheckoutRequestID": "ws_CO_DMZ_215482558_10122018133312795",
        "MerchantRequestID": "11209-2482748-1",
        "ResponseCode": "0"
    },
    "amount": 48744.15
}

The user at this point will recieve a USSD pop up, so they can complete the request

Whether they cancel or complete the request, a response will be pinged back to https://vitumob.com/mpesa endpoint