ScopePay API Documentation

Overview

ScopePay is a professional M-Pesa STK Push API aggregator. Two endpoints, simple JSON requests, instant payments.

Property	Value
Base URL	`https://scopepay.co.ke/`
Content-Type	`application/json`
Method	POST
Min Amount	KES 1
Max Amount	KES 150,000

Authentication

All API requests are authenticated via api_key and api_secret sent in the JSON request body.

Get your API keys: Login to Dashboard → API Keys and generate them. Save your secret — it's shown only once.

Initiate STK Push

POST /api/initiatestk.php

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key
`api_secret`	string	Yes	Your API secret
`account_id`	string	Yes	Your Linked Account ID
`amount`	integer	Yes	Amount in KES (min 1)
`phone`	string	Yes	Phone number (07XXXXXXXX or 01XXXXXXXX)
`reference`	string	Yes	Payment reference / description

Success Response (200)

{
    "success": true,
    "transaction_ref": "TXN-A8F3D2B9-45",
    "merchant_request_id": "29115-34620561-1",
    "checkout_request_id": "ws_CO_191220191020363925",
    "result_code": 0,
    "message": "STK Push initiated successfully"
}

Error Response (500)

{
    "error": "Payment initiation failed",
    "merchant_request_id": "",
    "checkout_request_id": "",
    "result_code": 1
}

Transaction Status

POST /api/transactionstatus.php

Request Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key
`api_secret`	string	Yes	Your API secret
`checkout_request_id`	string	Yes	From initiate STK response

Success Response (200)

{
    "success": true,
    "merchant_request_id": "29115-34620561-1",
    "checkout_request_id": "ws_CO_191220191020363925",
    "result_code": "0",
    "status": "paid",
    "amount": 100.00,
    "phone": "0712345678",
    "receipt": "PZ3DUJJ7GY",
    "description": "Order #12345",
    "created_at": "2026-02-18 12:34:56"
}

Error Response (404)

{
    "error": "Transaction not found"
}

Webhook Payload

When a payment completes, ScopePay sends a POST request to your configured webhook URL:

{
    "merchant_request_id": "29115-34620561-1",
    "checkout_request_id": "ws_CO_191220191020363925",
    "result_code": 0,
    "scopepay_ref": "TXN-A8F3D2B9-45",
    "account_id": 1,
    "customer_phone": "0712345678",
    "amount": 100.00,
    "fee": 0.00,
    "net_settled": 100.00,
    "mpesa_receipt": "PZ3DUJJ7GY",
    "description": "Order #12345",
    "status": "settled",
    "timestamp": "2026-02-18T12:34:56+03:00"
}

Important: Your webhook must respond with HTTP 200 within 5 seconds. Configure your webhook URL in Dashboard → Webhooks.

Error Codes

HTTP Code	Description	Solution
400	Bad Request / Missing params	Check required parameters
401	Invalid API credentials	Verify api_key and api_secret
403	No active subscription	Activate account in dashboard
404	Transaction not found	Check checkout_request_id
500	Server error	Contact support

Code Examples

cURL — Initiate STK Push

curl -X POST https://scopepay.co.ke/api/initiatestk.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret",
    "account_id": "your_account_id",
    "amount": 100,
    "phone": "0712345678",
    "reference": "Order #12345"
  }'

cURL — Transaction Status

curl -X POST https://scopepay.co.ke/api/transactionstatus.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret",
    "checkout_request_id": "ws_CO_191220191020363925"
  }'

PHP — Initiate STK Push

<?php
$url = 'https://scopepay.co.ke/api/initiatestk.php';

$payload = json_encode([
    'api_key'    => 'your_api_key',
    'api_secret' => 'your_api_secret',
    'account_id' => 'your_account_id',
    'amount'     => 100,
    'phone'      => '0712345678',
    'reference'  => 'Order #12345'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

PHP — Transaction Status

<?php
$url = 'https://scopepay.co.ke/api/transactionstatus.php';

$payload = json_encode([
    'api_key'             => 'your_api_key',
    'api_secret'          => 'your_api_secret',
    'checkout_request_id' => 'ws_CO_191220191020363925'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>