Documentation

Payment Notification

Last milestone

When a confirmation request is made, and the client completes the payment process by accepting and following the pop up instructions, a payment notification in form of a POST request is made to Project Mulla from the MPESA G2 API.


How this happens is Project Mulla provide it’s own CALLBACK_URL when making the initialisation Payment Request. On a successful payment confirmation from the Merchant’s client, the MPESA G2 API will make a HTTP POST request to Project Mulla as a success notification of the requested payment.

This POST request from the MPESA G2 API will be processed and Project Mulla will invoke a POST request to the MERCHANT_ENDPOINT you configured when deploying Project Mulla with the JSON payload - serialized - in the POST body.


An Example of the MPESA G2 API POST request

For example, if your MERCHANT_ENDPOINT is https://merchant-endpoint.com/mpesa/payment/complete then Project Mulla will make a POST request with the following JSON payload in the body. Since the POST body only accepts strings, the JSON has to serialized - stringified.

Our extra payload

All the extra_payload provided when initialisation a payment request is usually sent back as a BASE64 encrypted string value of the ENC_PARAMS. Project Mulla will decrypt this and attach it to the POST request JSON payload as an object before all the payload is serialized to a string.

The completion request made by Project Mulla to Merchant’s endpoint

POST https://merchant-endpoint.com/mpesa/payment

The POST body:

"{"response":{"msisdn":"254723001575","amount":"450","mpesa_trx_date":"2014-12-01 16:24:06","mpesa_trx_id":"6jk45hsjdhjjky5hjk36wdsgha","trx_status":"success","return_code":"00","description":"success","merchant_transaction_id":"320903","trx_id":"ds9d7f98asf809d8f9098sa098f9008f8"}}"

How the JSON looks like before serialization and after unserialization:

{
  "response": {
    "msisdn": "254723001575",
    "amount": "450",
    "mpesa_trx_date": "2014-12-01 16:24:06",
    "mpesa_trx_id": "6jk45hsjdhjjky5hjk36wdsgha",
    "trx_status": "success",
    "return_code": "00",
    "description": "success",
    "merchant_transaction_id": "320903",
    "trx_id": "ds9d7f98asf809d8f9098sa098f9008f8",
    "extra_payload": {
      "clientName": "Eugene Mutai",
      "clientLocation": "Kilimani",
      "delivery": "false"
    }
  }
}

NOTE: The JSON in the body is serialized and you are required to parse/unserialize it before you can have access to it’s values.