Mpesa Stk Push Init – Jenga Docs

Mpesa stk/ussd push initiate

This API allows merchants to initiate Mpesa STK/USSD pushes to Customers.

Contrary to Account-based API, the funds are credited to Jenga Wallet where one can settle to any bank account on-boarded on Jenga.
The funds are available for settlement on a real-time basis.

Test URL

POSThttps://uat.finserve.africa/api-checkout/mpesa-stk-push/v3.0/init

Live URL

POSThttps://api.finserve.africa/api-checkout/mpesa-stk-push/v3.0/init

Interface Definition

Interface ID	mpesaStkPush
Version	1.0
Interface Type	REST/JSON
Mode	Synchronous
Method	POST
Endpoint	/api-checkout/mpesa-stk-push/v3.0/init
Description	Initiate Mpesa STK Push

Request Parameters

Field	Description	Format	Req
order.orderReference	Order reference, should be unique per order	String	Y
order.orderAmount	Original order amount	Number	Y
order.orderCurrency	Currency of the order	String	Y
order.source	Source of the order, i.e, APICHECKOUT	String	Y
order.countryCode	Source country code i.e alpha-2 country code E.g KE	String	Y
order.description	Description of the order	String	Y
customer.name	Customer's name	String	Y
customer.email	Customer's email	String	Y
customer.phoneNumber	Customer's phone number	String	Y
customer.identityNumber	Customer's identity number	String	Y
customer.firstAddress	Customer's first address	String	N
customer.secondAddress	Customer's second address	String	N
payment.paymentReference	Payment reference, should be unique per request	String	Y
payment.paymentCurrency	Currency of the payment	String	Y
payment.channel	Channel of the payment, e.g., MOBILE	String	Y
payment.service	Payment service, i.e., MPESA	String	Y
payment.provider	Payment provider, i.e., JENGA	String	Y
payment.callbackUrl	Callback URL to notify merchant when the transaction is completed or failed	String	Y
payment.details.msisdn	Number to push the STK	String	Y
payment.details.paymentAmount	Amount to pay on the request	Number	Y

Example Request

POST /api-checkout/mpesa-stk-push/v3.0/init
Content-Type: application/json
Authorization: Bearer {{ access_token }}
Signature: (Generation Formula): order.orderReference, payment.paymentCurrency, payment.details.msisdn, payment.details.paymentAmount

Request Body

 
{
    "order": {
        "orderReference": "OR28922980077", //Order reference, should be unique per order 
        "orderAmount": 2, //Origininal order amount
        "orderCurrency": "KES",
        "source": "APICHECKOUT",
        "countryCode": "KE",
        "description": "Purchase"
    },
    "customer": {
        "name": "John Doe",
        "email": "xyx2@gmail.com",
        "phoneNumber": "0722000111",
        "identityNumber": "0000000",
        "firstAddress": "",
        "secondAddress": ""
    },
    "payment": {
        "paymentReference": "MKQR28922980073", //Should be unique per request
        "paymentCurrency": "KES",
        "channel": "MOBILE",
        "service": "MPESA",
        "provider": "JENGA",
        "callbackUrl": "https://webhook.site/5c74a733-1caa-4f10-b876-3df9c0d7453c",
        "details": {
            "msisdn": "0722000000", //Number to push the stk
            "paymentAmount": 2 //Amount to pay on the request
        }
    }
}

Response Parameters

Field	Description	Format	Req
status	Response status	String	Y
code	Response code	Number	Y
message	Response message	String	Y
data	Response data	Object	Y

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "status": true,
    "code": "0",
    "message": "Success. Request accepted for processing",
    "data": {
        "amount": 2.0,
        "charge": 1.0,
        "paymentReference": "MKQR28922980073",
        "invoiceNumber": "INVDBU",
        "orderReference": "OR28922980077",
        "amountDebited": 2.0
    }
}

Http Response Code	Status Code	Description
401	106401	Not Authorized to access this Telco,Kindly contact support@finserve.africa
200	-1	Transaction has been successfully acknowledged, await final transaction status on callback
200	106201	Failed to initiate push. Kindly try again after a few minutes or contact support@finserve.africa
500	106500	Error loading service
500	106501	Error mapping service

Jenga Callbacks

Once a payment is complete , you will receive a callback in this format if you provide a callback url on the request.
We dont recommend making your final decision based on this callback, but this can help when troubleshooting, We recommend the Complete Callback Response listed below.

Mpesa Confirmation Callback Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": true,
  "code": "0",
  "message": "The service request is processed successfully.",
  "transactionReference": "MKQR28922980073",
  "data": {
    "Body": {
      "stkCallback": {
        "MerchantRequestID": "0528-4964-bbde-4f38e64fe5f147817775",
        "CheckoutRequestID": "ws_CO_0908202416223944722000000",
        "ResultDesc": "The service request is processed successfully.",
        "ResultCode": 0,
        "CallbackMetadata": {
          "Item": [
            {
              "Value": 2,
              "Name": "Amount"
            },
            {
              "Value": "SH90HU7FO2",
              "Name": "MpesaReceiptNumber"
            },
            {
              "Name": "Balance"
            },
            {
              "Value": 20240809162247,
              "Name": "TransactionDate"
            },
            {
              "Value": 254722000000,
              "Name": "PhoneNumber"
            }
          ]
        }
      }
    }
  }
}

Complete Callback Response

We recommend registering a callback URL on Jenga HQ under Settings > IPNs as this is a confirmation of payment been processed successfully both on Mpesa and Jenga.
To find more about IPN callbacks navigate to IPN

Complete Callback Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "callbackType": "IPN",
  "customer": {
    "name": "John Doe",
    "mobileNumber": "0722000000",
    "reference": "OR28922980077"
  },
  "transaction": {
    "date": "2024-08-09 16:22:50",
    "reference": "SH90HU7FO2",
    "paymentMode": "MPESA",
    "amount": 2,
    "currency": "KES",
    "serviceCharge": 1,
    "billNumber": "INVDBU",
    "servedBy": "JENGA",
    "additionalInfo": "MPESA",
    "orderAmount": 2,
    "orderCurrency": "KES",
    "status": "SUCCESS",
    "remarks": "ED990222"
  },
  "bank": {
    "reference": "NONE",
    "transactionType": "C",
    "account": "NONE"
  }
}

Notifications

Sender ID: JENGA

 
~ Mpesa 
 
Mpesa payment confirmed. You have successfully completed your transaction of KES 5.00 to Spotify 
 Kenya on 13-06-2024 at 02:22:51 PM. Service charge, KES 0.00. Ref. SH90HU7FO2

Mpesa Stk Ussd Push Query Order Status