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 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	String	Y
merchant.accountNumber	Account number to be credited on payment completion	String	Y
merchant.name	Merchant name	String	Y
payment.ref	Payment Reference, Allowed length 6 to 12 alphanumeric characters ONLY	String	Y
payment.mobileNumber	Payer's mobile number with country Code prefix E.g 254763XXXXXX	String	Y
payment.telco	Payer's telco i.e Equitel	String	Y
payment.amount	Transaction amount, Up to 2 decimal places allowed	String	Y
payment.date	Transaction Date in the 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

⚠️

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 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, E.g by user
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": "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

Query Order Status Payment Link as API