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. 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 connected to your SmartPay account.

Obtaining API Credentials

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

Authentication

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

Authorization: your-api-key-here
Content-Type: application/json

Important: Never expose your API key in client-side code. Always keep it secure on your server.

Sandbox Testing

SmartPay provides a sandbox environment for testing your integration before going live. Use the following credentials:

• Base URL: https://sandbox-api.smartpaypesa.com/v1/
• Test Phone: 254712345678
• Test PIN: 123456

All sandbox transactions are simulated and do not move real money.

Initiate STK Push POST

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

Endpoint

POST https://api.smartpaypesa.com/v1/initiatestk/

Request Headers

Content-Type: application/json
Authorization: your-api-key-here

Request Parameters

Example Request (cURL)

curl -X POST https://api.smartpaypesa.com/v1/initiatestk/ \
  -H "Content-Type: application/json" \
  -H "Authorization: your-api-key" \
  -d '{"phone":"254712345678","amount":150,"account_reference":"INV-001","description":"Order Payment"}'

Example Request (PHP)

<?php
$apiKey = 'your-api-key';
$data = [
    'phone' => '254712345678',
    'amount' => 150,
    'account_reference' => 'INV-001',
    'description' => 'Order Payment'
];

$ch = curl_init('https://api.smartpaypesa.com/v1/initiatestk/');
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',
    'Authorization: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Success Response

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

Account Balance POST

Check your SmartPay account balance.

Endpoint

POST https://api.smartpaypesa.com/v1/initiatebalance/

Request Body

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

Response Example

{
  "status": "success",
  "account_info": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+254727856009",
    "account_number": "SP36413506",
    "balance": "435.00"
  }
}

Transaction Status POST

Check the status of an initiated STK Push transaction.

Endpoint

POST https://api.smartpaypesa.com/v1/transactionstatus/

Request Body

{
  "CheckoutRequestID": "ws_CO_17062025005554749727856009"
}

Response Example (Success)

{
  "Body": {
    "stkCallback": {
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {"Name": "Amount", "Value": 10},
          {"Name": "MpesaReceiptNumber", "Value": "TFH774CBH1"},
          {"Name": "PhoneNumber", "Value": 254727856009}
        ]
      }
    }
  }
}

SMS API POST

Send single or bulk SMS messages to Kenyan phone numbers. Each SMS unit costs 1 credit per 160 characters.

Headers

Content-Type: application/json
X-API-Key: your-api-key-here

Endpoint

POST https://api.smartpaypesa.com/v1/sms/

Request Parameters

Example Request (cURL)

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

Example Request (JavaScript)

fetch('https://api.smartpaypesa.com/v1/sms/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    phone: '0712345678',
    message: 'Payment received!'
  })
})
.then(res => res.json())
.then(data => console.log(data));

Success Response

{
  "status": "success",
  "message": "SMS sent successfully",
  "data": {
    "transaction_id": "5713595232279350695",
    "mobile": "254712345678",
    "sms_parts": 1,
    "characters": 40,
    "cost": 1,
    "remaining_balance": 99
  }
}

Check SMS Balance GET

Endpoint

GET https://api.smartpaypesa.com/v1/sms/balance

Headers

X-API-Key: your-api-key-here

Response Example

{
  "status": "success",
  "data": {
    "sms_balance": 96,
    "user": {"name": "John Doe", "email": "john@example.com"},
    "api_calls_remaining": "unlimited"
  }
}

SMS Pricing

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

Webhooks (Callback URL)

Webhooks allow SmartPay to send real-time payment notifications to your server whenever a transaction completes.

How to Configure

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

Webhook Payload Example

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

Error Response Codes

Supported Banks & Paybills

SmartPay supports integration with the following banks via Paybill numbers:

Full list of 40+ banks available in your dashboard.

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
• Use webhooks instead of polling where possible
• Store transaction IDs for reconciliation