SmartPay API Documentation

Getting Started

Welcome to the SmartPay API documentation. This guide will help you understand how to integrate our payment services into your applications. Please review this documentation carefully to understand how our web service works. Basic JSON and HTTP knowledge is required to implement the API.

What is SmartPay

SmartPay is a service that enables you to collect payments on your website or mobile app through M-Pesa STK Push. The money is automatically sent to your M-Pesa till number, paybill number, or bank account that you have connected to your SmartPay account.

Obtaining API Credentials

To get started with our API integration, you need an API Key. Follow these steps to obtain one:

1. Login to your SmartPay Account
2. Navigate to Linked Accounts and copy your API Key
3. If you see "no data", go to Account Setup and link your Till, Paybill, or Bank Account
4. You'll then be redirected to Linked Accounts where you can get your API Key

Initiate STK Push

The STK Push API allows you to initiate M-Pesa payments by sending a push notification to the customer's phone.

Endpoint

Headers

Request Parameters

Request Headers

POST /v1/initiatestk HTTP/1.1
Host: api.smartpaypesa.com
Content-Type: application/json
Authorization: dac85c2c4078a202ef1c2edf87bcd1dba08bb3867f14de3366efd5722c6e9d33
                

Request Body

{
  "phone": "254712345678",
  "amount": 150,
  "account_reference": "NETON_101",
  "description": "Payment for SmartPlan"
}

Response Example

{
  "success": true,
  "message": "STK Push initiated successfully",
  "checkoutRequestID": "ws_CO_16062025160832822727856009",
  "merchantRequestID": "aea5-4f44-b4a1-d9044446ee461957335"
}

Success Callback (Final STK Response)

{
  "success": true,
  "message": "Payment completed successfully",
  "transaction": {
    "receipt_number": "SIS88JC7AM",
    "amount": 150,
    "status": "completed",
    "phone": "254712345678",
    "date": "2025-06-16 16:08:32",
    "checkout_request_id": "ws_CO_16062025160832822727856009"
  }
}

Account info - Balance

Check your account information including balance.

Endpoint

Headers

Request Parameters

Request Example

{
  "phone": "254712345678",
  "account_reference": "BALANCE"
}

Response Example

{
  "status": "success",
  "account_info": {
    "name": "Elvis Keari",
    "email": "kearielvis@gmail.com",
    "phone": "+254727856009",
    "account_number": "SP36413506",
    "balance": "435.00"
  }
}

Transaction Status

Check the status of an initiated STK Push transaction.

Endpoint

Headers

Request Parameters

Request Example

{
  "CheckoutRequestID": "ws_CO_17062025005554749727856009"
}

Response Example

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "aea5-4f44-b4a1-d9044446ee463545184",
      "CheckoutRequestID": "ws_CO_17062025005554749727856009",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {
            "Name": "Amount",
            "Value": 10
          },
          {
            "Name": "MpesaReceiptNumber",
            "Value": "TFH774CBH1"
          },
          {
            "Name": "TransactionDate",
            "Value": 20250617005603
          },
          {
            "Name": "PhoneNumber",
            "Value": 254727856009
          }
        ]
      }
    }
  }
}

SMS API

SmartPay's SMS API allows you to send bulk and single SMS messages to Kenyan phone numbers. Each SMS unit costs 1 credit per 160 characters.

Authentication

All SMS API requests require authentication using your API key. Include it in the request header:

X-API-Key: dac85c2c4078a202ef1c2edf87bcd1dba08bb3867f14de3366efd5722c6e9d33

Send SMS

Send a single SMS message to a Kenyan phone number. The API automatically handles message splitting for long messages (over 160 characters).

Endpoint

Headers

Request Parameters

Request Example

{
                "phone": "0712345678",
                "message": "Your payment of KES 1,500 has been received successfully. Thank you for choosing SmartPay!"
            }

cURL Example

curl -X POST https://api.smartpaypesa.com/v1/sms/ \
              -H "Content-Type: application/json" \
              -H "X-API-Key: your-api-key-here" \
              -d '{"phone":"0712345678","message":"Hello from SmartPay API!"}'

PHP Example

<?php
            $api_key = 'your-api-key-here';
            $url = 'https://api.smartpaypesa.com/v1/sms/';
            
            $data = [
                'phone' => '0712345678',
                'message' => 'Hello from SmartPay API!'
            ];
            
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            curl_setopt($ch, CURLOPT_HTTPHEADER, [
                'Content-Type: application/json',
                'X-API-Key: ' . $api_key
            ]);
            
            $response = curl_exec($ch);
            curl_close($ch);
            
            echo $response;
            ?>

JavaScript Example

fetch('https://api.smartpaypesa.com/v1/sms/', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-API-Key': 'your-api-key-here'
                },
                body: JSON.stringify({
                    phone: '0712345678',
                    message: 'Hello from SmartPay API!'
                })
            })
            .then(response => response.json())
            .then(data => console.log(data))
            .catch(error => console.error('Error:', error));

Python Example

import requests
            import json
            
            api_key = 'your-api-key-here'
            url = 'https://api.smartpaypesa.com/v1/sms/'
            
            headers = {
                'Content-Type': 'application/json',
                'X-API-Key': api_key
            }
            
            data = {
                'phone': '0712345678',
                'message': 'Hello from SmartPay API!'
            }
            
            response = requests.post(url, headers=headers, json=data)
            print(response.json())

Success Response

{
                "status": "success",
                "message": "SMS sent successfully",
                "data": {
                    "transaction_id": "5713595232279350695",
                    "mobile": "254712345678",
                    "sms_parts": 1,
                    "characters": 40,
                    "cost": 1,
                    "remaining_balance": 99,
                    "gateway_response": {
                        "status": "success",
                        "mobile": "254712345678",
                        "invalidMobile": "",
                        "transactionId": "5713595232279350695",
                        "statusCode": "200",
                        "reason": "success",
                        "msgId": "",
                        "requestTime": "2026-02-21 11:36:15"
                    }
                }
            }

Long Message Response (Multiple SMS Parts)

{
                "status": "success",
                "message": "SMS sent successfully",
                "data": {
                    "transaction_id": "SMS_69996e80b7c1e",
                    "mobile": "254727856009",
                    "sms_parts": 3,
                    "characters": 370,
                    "cost": 3,
                    "remaining_balance": 96,
                    "gateway_response": null
                }
            }

Check SMS Balance

Check your available SMS credits balance.

Endpoint

Headers

cURL Example

curl -X GET https://api.smartpaypesa.com/v1/sms/balance \
              -H "X-API-Key: your-api-key-here"

Response Example

{
                "status": "success",
                "data": {
                    "sms_balance": 96,
                    "user": {
                        "name": "Elvis Keari",
                        "email": "kearielvis@gmail.com"
                    },
                    "api_calls_remaining": "unlimited"
                }
            }

SMS Pricing

Note: Each additional 160 characters (or part thereof) costs 1 additional credit.

SMS Error Codes

Best Practices for SMS API

• Phone Number Format: Always use Kenyan format (07XXXXXXXX, 01XXXXXXXX, or 254XXXXXXXX)
• Message Length: Keep messages under 160 characters to save credits (1 credit per SMS)
• Balance Check: Always check balance before sending bulk messages
• Error Handling: Implement proper error handling for all response codes
• Rate Limiting: Space out bulk SMS sends to avoid being flagged as spam
• Transaction IDs: Store transaction IDs for tracking and reconciliation

Error Response Codes

Error Response Example

{
  "ResponseCode": "1032",
  "ResponseDescription": "Request cancelled by user"
}

Webhooks (Callback URL)

A webhook in programming is a method for one application to send real-time data to another whenever a specific event occurs. It works by setting up a callback URL on the receiving application, which the sending application will call with a payload (usually in JSON format) when the event is triggered. This allows for asynchronous communication and enables applications to respond immediately to changes or actions without the need for continuous polling. Webhooks are commonly used in APIs for notifications, updates, and integrations.

How to Configure Webhook in SmartPay

1. Login into your SmartPay Account
2. Open the Sidebar Menu
3. Click API
4. Click Create APP
5. Choose Payment destination
6. Add Callback URL
7. Click Save

Webhook Payload Example

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "aea5-4f44-b4a1-d9044446ee463545184",
      "CheckoutRequestID": "ws_CO_17062025005554749727856009",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {
            "Name": "Amount",
            "Value": 10
          },
          {
            "Name": "MpesaReceiptNumber",
            "Value": "TFH774CBH1"
          },
          {
            "Name": "TransactionDate",
            "Value": 20250617005603
          },
          {
            "Name": "PhoneNumber",
            "Value": 254727856009
          }
        ]
      }
    }
  }
}

Supported Banks

SmartPay supports integration with the following banks and paybill numbers:

Best Practices

Security Recommendations

• Always use HTTPS for all API requests
• Never expose your API key in client-side code
• Implement IP whitelisting for production API keys
• Rotate API keys periodically
• Validate all callback data before processing

Performance Tips

• Implement proper error handling and retry logic
• Cache frequently accessed data
• Use webhooks instead of polling where possible
• Batch requests when processing multiple transactions

Testing Guidelines

• Test with small amounts first
• Verify callback URL functionality
• Test all error scenarios
• Simulate network failures and timeouts