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

Live URL

Interface Definition

Request Parameters

Example Request

Signature

merchant.accountNumber+payment.ref+payment.mobileNumber+payment.telco+payment.amount+payment.currency

POST /v3-apis/payment-api/v3.0/stkussdpush/initiate
Content-Type: application/json
Authorization: Bearer {{access_token}}
Signature: {{ generated_signature }}

{
    "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"
    }
}

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

**Jenga Callback **

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

Callback Response Example

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

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"
}

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"
}

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

Error Responses

400 Bad Request

Missing or invalid parameters in the request body.

{
  "status": false,
  "code": 400,
  "message": "Invalid request parameters",
  "error_code": "INVALID_REQUEST"
}

401 Unauthorized

Invalid or expired access token.

{
  "status": false,
  "code": 401,
  "message": "Invalid or expired access token",
  "error_code": "UNAUTHORIZED"
}

403 Forbidden

Valid credentials but invalid signature or insufficient permissions.

{
  "status": false,
  "code": 403,
  "message": "Invalid signature or insufficient permissions",
  "error_code": "FORBIDDEN"
}

404 Not Found

Account not found or invalid account number.

{
  "status": false,
  "code": 404,
  "message": "Source or destination account not found",
  "error_code": "ACCOUNT_NOT_FOUND"
}

Transaction Status Errors

📖 Step-by-Step Guide

Step 1: 🔑 Set Up Security Keys

Generate your private and public key pair and share your public key with Finserve. See the Security & Signatures Documentation (opens in a new tab) for detailed instructions.

Step 2: 🎫 Authenticate

Obtain an access token using the authentication endpoint. See the Authentication API documentation (opens in a new tab) for details.

Step 3: 📋 Prepare Transaction Details

Gather all required information.

Step 4: ✍️ Generate Signature

Create the signature string by concatenating in this exact order:

merchant.accountNumber+payment.ref+payment.mobileNumber+payment.telco+payment.amount+payment.currency

Sign this string using your private key, then Base64 encode the result.

Step 5: 📝 Set Up Headers

Include the following headers in your request:

• Content-Type: application/json
• Authorization: Bearer [your_access_token]
• Signature: [your_base64_encoded_signature]

Step 6: 🔧 Construct Request Body

Create a JSON object with all required fields following the structure shown in the example request.

Step 7: 🚀 Send POST Request

Make a POST request to the internal bank transfer endpoint with your headers and body.

🌍 Supported Countries & Currencies

Best Practices

1. ** Security**

   • Store your private key securely and never expose it in client-side code or version control
   • Always use HTTPS for API requests
   • Store access tokens securely
   • Regenerate signatures for each request

2. ** Signature Generation**

   • Ensure exact string concatenation order: merchant.accountNumber+payment.ref+payment.mobileNumber+payment.telco+payment.amount+payment.currency
   • Do not include spaces, separators, or special characters in the concatenated string
   • Always Base64 encode the signature before including it in headers
   • Verify the values in the signature match exactly with the request body values

3. ** Transaction Reference**

   • Use unique reference numbers for each transaction
   • Implement a reference generation system to avoid duplicates
   • Store reference numbers for reconciliation and audit purposes
   • Never reuse reference numbers, even for failed transactions

4. Amount Formatting

   • Always use decimal format with two decimal places (e.g., "500.00")
   • Pass amounts as strings, not numbers
   • Ensure the amount is positive and within allowed limits
   • Verify amount matches exactly in signature and request body

5. Error Handling

   • Implement retry logic with exponential backoff for transient errors
   • Log transaction attempts and responses for audit purposes
   • Handle signature validation errors by regenerating the signature

6. Testing

   • Always test with the UAT endpoint before using the live endpoint
   • Use test account numbers provided in the documentation
   • Verify signature generation with sample data first
   • Test error scenarios to ensure proper handling

7. Data Validation

   • Validate all account numbers match the expected format
   • Verify country codes are valid and supported
   • Ensure transfer dates are in the correct format (YYYY-MM-DD)
   • Validate currency codes match the destination country

Troubleshooting

Invalid Signature Error (403)

If you receive a 403 error with "Invalid signature":

1. Verify the concatenation order: merchant.accountNumber+payment.ref+payment.mobileNumber+payment.telco+payment.amount+payment.currency
2. Ensure no spaces or separators are included in the concatenated string
3. Check that the signature is Base64 encoded
4. Verify your public key is correctly registered with us
5. Ensure the values in the signature match exactly with the request body values

Common Signature Mistakes

• Using wrong concatenation order
• Adding spaces or separators between values
• Not Base64 encoding the final signature
• Values in signature don't match request body values

Support

For questions or issues with this API:

• Email: support@finserve.africa