Guides & Tutorials
Jenga API
Receive Money
Equitel STK / USSD Push
Equitel Stk Ussd Push

Equitel STK/USSD Push Initiate

This API allows partners to initiate STK or USSD pushes to Telco MNOs for payment transactions via Equitel.

  • STK Push allows a customer to select an account to debit from whereas for USSD Push it debits the primary account of the customer.
  • Depending on the need, both allows customer to make payment with minimal interaction. 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 IDstkUssdPushToTelcos
version1.0
Interface TypeREST/JSON
ModeSynchronous
MethodPOST
Endpoint/v3-apis/payment-api/v3.0/stkussdpush/initiate
DescriptionTelco STK/USSD Push

Request Parameters

FieldDescriptionFormatReq
merchant.countryCodeMerchant country codeStringY
merchant.accountNumberAccount number to be credited on payment completionStringY
merchant.nameMerchant nameStringY
payment.refPayment Reference, Allowed length 6 to 12 alphanumeric characters ONLYStringY
payment.mobileNumberPayer's mobile number with country Code prefix E.g 254763XXXXXXStringY
payment.telcoPayer's telco i.e EquitelStringY
payment.amountTransaction amount, Up to 2 decimal places allowedStringY
payment.dateTransaction Date in the format YYYY-MM-DDStringY
payment.callBackUrlCallback URL to notify merchant when the transaction has completed or failedStringY
payment.pushTypeEither STK or USSDStringY

Example Request

⚠️

In the example below, replace placeholders like {{ access_token }}, https://webhook.site/6173e296-a2b0-4fb5-a06e-bfbb2e352e30, and other variables with actual values.

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
Equitel Example Request
{
    "merchant": {
        "accountNumber": "0170194290581",
        "countryCode": "KE",
        "name": "Sportify Ltd"
    },
    "payment": {
        "ref": "MPS3883889822982",
        "amount": "5.00",
        "currency": "KES",
        "telco": "Equitel",
        "mobileNumber": "254764555291",
        "date": "2024-08-13",
        "callBackUrl": "https://webhook.site/6173e296-a2b0-4fb5-a06e-bfbb2e352e30",
        "pushType": "STK"
    }
}
Equitel Example Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "status": true,
    "code": -1,
    "message": "Transaction has been successfully acknowledged, await final transaction status on callback",
    "reference": "MPS3883889822982",
    "transactionId": "MPS3883889822982"
}

HTTP Response Codes

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
400400101Transaction 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.

codecode descriptionDescription
0PENDINGRequest pending to be processed
1FAILEDTransaction Failed due to various reasons
2AWAITING_THIRD_PARTY_SETTLEMENTTransaction Successful - Awaiting Third Party Settlement (to be settled manually)
3COMPLETED/CREDITEDTransaction completed successfully and credited to merchant
4AWAITING-SETTLEMENTTransaction was successful, But failed to credit merchant account
5CANCELLEDTransaction was Cancelled, E.g by user
6CANCELLEDTransaction was Cancelled, E.g by user
7REJECTEDTransaction rejected due to validation errors

Callback Response Example

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

Error Callback Scenarios

Invalid Pin
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "status": false,
  "code": 1,
  "message": "Invalid pin",
  "transactionReference": "MPS3883889822033",
  "mobileNumber": "254764555291",
  "debitedAmount": 5,
  "requestAmount": 5,
  "charge": 1,
  "currency": "KES",
  "telco": "Equitel"
}
Maximum Amount Exceeded
HTTP/1.1 200 OK
Content-Type: application/json
 
{
 
  "status": false,
  "code": 1,
  "message": "MaximumAmountExceeded",
  "transactionReference": "MPS3883889822033",
  "mobileNumber": "254764555291",
  "debitedAmount": 53000,
  "requestAmount": 53000,
  "charge": 53,
  "currency": "KES",
  "telco": "Equitel"
}
Insufficient Fund
HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "status": false,
    "code": "1",
    "message": "InsufficientFund",
    "transactionReference": "SP1717672371",
    "mobileNumber": "254764555291",
    "debitedAmount": 150000,
    "requestAmount": 150000,
    "charge": 1500,
    "currency": "KES",
    "telco": "Equitel"
}
Notifications
Sender ID: JENGA

Equitel STK

Equitel 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. MPS3883889822982

Equitel USSD

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