API Explorer
Receive Money
M-Pesa STK push
Wallet Based Settlement
Initiate Request

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 IDmpesaStkPush
Version1.0
Interface TypeREST/JSON
ModeSynchronous
MethodPOST
Endpoint/api-checkout/mpesa-stk-push/v3.0/init
DescriptionInitiate Mpesa STK Push

Request Parameters

FieldDescriptionFormatReq
order.orderReferenceOrder reference, should be unique per orderStringY
order.orderAmountOriginal order amountNumberY
order.orderCurrencyCurrency of the orderStringY
order.sourceSource of the order, i.e, APICHECKOUTStringY
order.countryCodeSource country code i.e alpha-2 country code E.g KEStringY
order.descriptionDescription of the orderStringY
customer.nameCustomer's nameStringY
customer.emailCustomer's emailStringY
customer.phoneNumberCustomer's phone numberStringY
customer.identityNumberCustomer's identity numberStringY
customer.firstAddressCustomer's first addressStringN
customer.secondAddressCustomer's second addressStringN
payment.paymentReferencePayment reference, should be unique per requestStringY
payment.paymentCurrencyCurrency of the paymentStringY
payment.channelChannel of the payment, e.g., MOBILEStringY
payment.servicePayment service, i.e., MPESAStringY
payment.providerPayment provider, i.e., JENGAStringY
payment.callbackUrlCallback URL to notify merchant when the transaction is completed or failedStringY
payment.details.msisdnNumber to push the STKStringY
payment.details.paymentAmountAmount to pay on the requestNumberY

Example Request

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

FieldDescriptionFormatReq
statusResponse statusStringY
codeResponse codeNumberY
messageResponse messageStringY
dataResponse dataObjectY

Example Response

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 CodeStatus CodeDescription
401106401Not Authorized to access this Telco,Kindly contact support@finserve.africa
200-1Transaction has been successfully acknowledged, await final transaction status on callback
200106201Failed to initiate push. Kindly try again after a few minutes or contact support@finserve.africa
500106500Error loading service
500106501Error 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