Mpesa Stk Ussd Push – Jenga Docs

Mpesa STK/USSD Push Initiate (Account-Based Settlement)

This API allows partners to initiate Mpesa STK or USSD pushes to Mpesa Customers, with a real-time settlement to an account supplied on the request.

NB: Both STK and USSD push requests are delivered to the customer as USSD Push by Mpesa (Safaricom).

Test URL

POSThttps://uat.finserve.africa/v3-apis/payment-api/v3.0/stkussdpush/initiate

Live URL

POSThttps://api.finserve.africa/v3-apis/payment-api/v3.0/stkussdpush/initiate

Interface Definition

Interface ID	stkUssdPushToTelcos
version	1.0
Interface Type	REST/JSON
Mode	Synchronous
Method	POST
Endpoint	v3-apis/payment-api/v3.0/stkussdpush/initiate
Description	Telco STK/USSD Push

Request Parameters

Field	Description	Format	Req
merchant.countryCode	Merchant country code , Alpha-2 country code E.g KE	String	Y
merchant.accountNumber	Account number to be credited on payment completion	String	Y
merchant.name	Merchant name	String	Y
payment.ref	Payment Reference.For now we support up to 6 alphanumeric characters length but will later update to more characters.	String	Y
payment.mobileNumber	Payer's mobile number with country code prefix E.g 254722XXXXXX	String	Y
payment.telco	Payer's telco, e.g. Safaricom	String	Y
payment.amount	Transaction amount with upto to 2 decimals places. NB. this will rounded up to a whole number during processing	String	Y
payment.date	Transaction Date with format YYYY-MM-DD	String	Y
payment.callBackUrl	Callback URL to notify merchant when the transaction has completed or failed	String	Y
payment.pushType	Either STK or USSD	String	Y

Example Request

POST /v3-apis/payment-api/v3.0/stkussdpush/initiate
Content-Type: application/json
Authorization: Bearer {{ access_token }}
Signature: merchant.accountNumber+payment.ref+payment.mobileNumber+payment.telco+payment.amount+payment.currency

Body

Example Mpesa Request

{
    "merchant": {
        "accountNumber": "0170194290581", //account to be credited once customers makes payments
        "countryCode": "KE",
        "name": "Sportify Ltd"
    },
    "payment": {
        "ref": "X67KFH",
        "amount": "5.00",
        "currency": "KES",
        "telco": "Safafricom",
        "mobileNumber": "254722000000",
        "date": "2024-06-13",
        "callBackUrl": "https://webhook.site/c2d06f1e-3602-4404-a507-43359ef648d9",
        "pushType":"USSD"
        
    }
}

Example Mpesa Response

 
{
    "status": true,
    "code": -1,
    "message": "Transaction has been successfully acknowledged, await final transaction status on callback",
    "reference": "X67KFH",
    "transactionId": "X67KFH"
}

HTTP Response Codes

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
400	400101	Transaction with the same reference already exists

**Jenga Callback **

The below info will be sent to the url provided on the request body as a POST request.

code	code description	Description
0	PENDING	Request pending to be processed
1	FAILED	Transaction Failed due to various reasons
2	AWAITING_THIRD_PARTY_SETTLEMENT	Transaction Successful - Awaiting Third Party Settlement (to be settled manually)
3	COMPLETED/CREDITED	Transaction completed successfully and credited to merchant
4	AWAITING-SETTLEMENT	Transaction was successful, But failed to credit merchant account
5	CANCELLED	Transaction was Cancelled, E.g by user
6	CANCELLED	Transaction was Cancelled
7	REJECTED	Transaction rejected due to validation errors

Callback Response Example

Transaction Successful

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": true,
  "code": 3,
  "message": "Transaction Successful - Settled",
  "transactionReference": "X67KFH",
  "telcoReference": "SH98HGX9JE",
  "mobileNumber": "254722000000",
  "currency": "KES",
  "requestAmount": 5,
  "debitedAmount": 5,
  "charge": 1,
  "telco": "Safaricom"
}

Error Callback Scenarios

The initiator information is invalid.

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "status": false,
  "code": 7,
  "message": "The initiator information is invalid.",
  "transactionReference": "M92J43",
  "telcoReference": "",
  "mobileNumber": "254722000000",
  "currency": "KES",
  "requestAmount": 5,
  "debitedAmount": 5,
  "charge": 1,
  "telco": "Safaricom"
}

Notifications

Sender ID: JENGA

Mpesa STK

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. SH98HGX9JE

Mpesa USSD

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

Bill Validation Initiate Request