EQOPAY API Documentation
EQOPAY is a REST API for accepting M-Pesa payments in Kenya. Send a payment prompt to your customer's phone, check the result, and get notified the moment money lands in your Till, Paybill or bank account.
Base URL: https://api.eqopay.co.ke
- Accept M-Pesa payments via STK Push to a Till, Paybill or bank account
- Check the status of any transaction
- Receive real-time webhook notifications on your callback URL
- Share no-code payment pages with your customers
- Link several accounts under one EQOPAY user
- Money goes straight to your account. EQOPAY never holds your funds.
Authentication
Every request includes two credentials in the JSON body:
| Parameter | Type | Description |
|---|---|---|
api_key | string | Your API key. Find it under Linked accounts → Manage. Each linked account has its own keys. |
email | string | The email address registered on your EQOPAY account |
Keys starting sk_test_ simulate payments for free; sk_live_ keys move real money. You can also send the key as Authorization: Bearer <api_key> instead of api_key + email. All requests use Content-Type: application/json.
Quick Start
- Create an account at eqopay.co.ke and log in.
- Link a payment account: your Till number, Paybill number, or bank paybill and account number.
- Activate it with a subscription paid by M-Pesa from the dashboard (see Subscription & Pricing).
- Make your first API call to
/v1/stkpushwith yourapi_keyandemail.
STK Push: Initiate Payment
POSTBASE/v1/stkpush
Sends an M-Pesa payment prompt to the customer's phone. The customer enters their M-Pesa PIN to complete the payment.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | Your API key |
email | string | Yes | Your registered email |
amount | string | Yes | Amount in KES (whole shillings, minimum 1) |
msisdn | string | Yes | Customer phone, e.g. 0712345678 or 254712345678 |
reference | string | Yes | Payment reference or description, e.g. an order number |
account_number | string | Optional | Required for Paybill accounts: the account the customer is paying |
Success response
{
"ResponseCode": "0",
"success": "200",
"message": "Please enter your MPESA PIN to complete the transaction",
"transaction_request_id": "txn_k2m9x0q8w1e4r7t5y3u6",
"MerchantRequestID": "29115-34620561-1",
"CheckoutRequestID": "ws_CO_123456789"
}
Error response
{
"ResultCode": "102",
"errorMessage": "Request is missing required api_key!"
}
Transaction Status
POSTBASE/v1/tstatus
Checks the status of a transaction using the transaction_request_id returned by STK Push.
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | Your API key |
email | string | Yes | Your registered email |
transaction_request_id | string | Yes | The ID from the STK Push response |
Success response
{
"ResultCode": "200",
"ResultDesc": "Success",
"TransactionStatus": "Completed",
"TransactionReceipt": "SHJ7ABCDEF",
"TransactionAmount": "100.00",
"Msisdn": "254712345678",
"TransactionDate": "20261112153045",
"TransactionReference": "ORDER-001",
"CheckoutRequestID": "ws_CO_123456789",
"MerchantRequestID": "29115-34620561-1"
}
TransactionStatus is one of Pending, Completed, Failed or Cancelled. A pending payment is checked with Safaricom automatically, so polling this endpoint is a reliable fallback if a webhook is missed.Webhooks (Callbacks)
Set your callback URL in the dashboard under Webhooks → Add webhook. Callback URLs must be public https:// addresses; private, internal and local addresses are rejected. EQOPAY sends a POST request to it when a transaction is completed, failed or cancelled. ResponseCode 0 means the payment succeeded; any other value is the failure code (see Error Codes).
{
"ResponseCode": 0,
"ResponseDescription": "Success",
"MerchantRequestID": "29115-34620561-1",
"CheckoutRequestID": "ws_CO_123456789",
"TransactionID": "txn_k2m9x0q8w1e4r7t5y3u6",
"TransactionAmount": 100,
"TransactionReceipt": "SHJ7ABCDEF",
"TransactionDate": "20261112153045",
"TransactionReference": "ORDER-001",
"Msisdn": "254712345678"
}
Respond with HTTP 200. Failed deliveries are retried up to 4 times and logged in your dashboard, where you can resend them. Every webhook carries an X-Eqopay-Signature: t=<timestamp>,v1=<hmac> header: HMAC-SHA256 of t + "." + raw body with the signing secret shown on the Webhooks page. Verify it to confirm the request came from EQOPAY.
Late results and review flags
M-Pesa results can arrive late. If a customer pays after EQOPAY has already marked the payment expired (no answer within 5 minutes), Safaricom's confirmation is not dropped: the payment changes to success and you get a second webhook with ResponseCode 0 for the same TransactionID. Your handler should accept a success after a failure for the same transaction, and check whether the order was already cancelled.
A payment is flagged Needs review in the dashboard (and needs_review: true in the API) when:
- it succeeded after being marked unsuccessful (above);
- Safaricom reports a different amount or phone number than requested. If less was paid than requested, the payment is not reported as successful: it is marked
failedand the receipt is kept so you can refund or ask for the balance; - Safaricom sends conflicting results or a second receipt.
Every result, including repeats and rejected callbacks, is kept in the transaction's History in the dashboard.
Test phone numbers
With a sk_test_ key no real prompt is sent. Any number succeeds, except:
| Phone | Simulated outcome |
|---|---|
254700000001 | Failed: insufficient balance |
254700000002 | Cancelled by the customer |
254700000003 | Expired: customer didn't respond |
254700000004 | Failed: initiator error |
254700000005 | Expires first, then a late success arrives (two webhooks; flagged for review) |
254700000006 | Customer pays KES 1 less than requested (failed; flagged for review) |
Webhook Handler Sample
<?php
// webhook.php: receives EQOPAY payment notifications
$payload = file_get_contents("php://input");
$data = json_decode($payload, true);
if (!$data || !isset($data["TransactionID"])) {
http_response_code(400);
exit("Invalid payload");
}
// Optional but recommended: verify the signature
$sig = [];
parse_str(str_replace(",", "&", $_SERVER["HTTP_X_EQOPAY_SIGNATURE"] ?? ""), $sig);
$expected = hash_hmac("sha256", ($sig["t"] ?? "") . "." . $payload, getenv("EQOPAY_WEBHOOK_SECRET"));
if (!hash_equals($expected, $sig["v1"] ?? "")) {
http_response_code(401);
exit("Bad signature");
}
if ($data["ResponseCode"] == 0) {
// Payment successful: mark the order paid (only once per TransactionID)
$receipt = $data["TransactionReceipt"];
$amount = $data["TransactionAmount"];
$reference = $data["TransactionReference"];
// ... update your database ...
} else {
// Payment failed or was cancelled
$reason = $data["ResponseDescription"];
// ... update your database ...
}
http_response_code(200);
echo "OK";Payment Pages (No-Code)
For non-developers
No website or developer? Every linked account gets a hosted payment page at https://eqopay.co.ke/pay/your-business-name. Share the link on WhatsApp, SMS, social media or a QR code. Customers don't need an account to pay.
- Link your Till, Paybill or bank account in the dashboard.
- Activate the account with a subscription.
- Copy your payment page link from Linked accounts and share it.
- The customer opens the link, enters their phone number and amount (plus account number for a Paybill), and approves the M-Pesa prompt.
Account Types
| Account type | Customer enters | Description |
|---|---|---|
| Till Number | Phone, amount | Lipa Na M-Pesa Buy Goods. Money goes straight into your till. |
| Paybill | Phone, amount, account number | The customer supplies the account number. Money goes straight into your paybill. |
| Bank Account | Phone, amount | Paid through your bank's M-Pesa paybill. Your account number is preset when you link the account, so money goes straight into your bank. |
PHP Sample
Initiate STK Push
<?php
$ch = curl_init("BASE/v1/stkpush");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"api_key" => "your_api_key",
"email" => "your@email.com",
"amount" => "100",
"msisdn" => "0712345678",
"reference" => "ORDER-001",
]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($response["ResponseCode"] ?? null) === "0") {
$requestId = $response["transaction_request_id"]; // save this with the order
echo "Prompt sent. Request ID: " . $requestId;
} else {
echo "Error: " . ($response["errorMessage"] ?? "Unknown error");
}
Check Transaction Status
<?php
$ch = curl_init("BASE/v1/tstatus");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"api_key" => "your_api_key",
"email" => "your@email.com",
"transaction_request_id" => $requestId,
]),
]);
$status = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $status["TransactionStatus"]; // Pending | Completed | Failed | Cancelled
Python Sample
import requests
BASE_URL = "BASE"
API_KEY = "your_api_key"
EMAIL = "your@email.com"
def initiate_payment(amount, phone, reference):
r = requests.post(f"{BASE_URL}/v1/stkpush", json={
"api_key": API_KEY, "email": EMAIL,
"amount": str(amount), "msisdn": phone, "reference": reference,
}, timeout=30)
return r.json()
def check_status(request_id):
r = requests.post(f"{BASE_URL}/v1/tstatus", json={
"api_key": API_KEY, "email": EMAIL, "transaction_request_id": request_id,
}, timeout=30)
return r.json()
result = initiate_payment(100, "0712345678", "ORDER-001")
if result.get("ResponseCode") == "0":
print(check_status(result["transaction_request_id"])["TransactionStatus"])
else:
print("Error:", result.get("errorMessage"))
Node.js Sample
const axios = require("axios");
const BASE_URL = "BASE";
const API_KEY = "your_api_key";
const EMAIL = "your@email.com";
async function initiatePayment(amount, phone, reference) {
const { data } = await axios.post(`${BASE_URL}/v1/stkpush`, {
api_key: API_KEY, email: EMAIL, amount: String(amount), msisdn: phone, reference,
});
return data;
}
async function checkStatus(requestId) {
const { data } = await axios.post(`${BASE_URL}/v1/tstatus`, {
api_key: API_KEY, email: EMAIL, transaction_request_id: requestId,
});
return data;
}
// Usage
(async () => {
const res = await initiatePayment(100, "0712345678", "ORDER-001");
if (res.ResponseCode === "0") {
const status = await checkStatus(res.transaction_request_id);
console.log(status.TransactionStatus);
}
})().catch((err) => console.error(err.response?.data || err.message));
JavaScript (Fetch) Sample
Run this from a server-side JavaScript runtime (Node 18+, Deno, Bun, Cloudflare Workers) so your API key is never exposed in a browser.
const BASE_URL = "BASE";
async function initiatePayment(amount, phone, reference) {
const res = await fetch(`${BASE_URL}/v1/stkpush`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
api_key: "your_api_key", email: "your@email.com",
amount: String(amount), msisdn: phone, reference,
}),
});
return res.json();
}
async function checkStatus(requestId) {
const res = await fetch(`${BASE_URL}/v1/tstatus`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ api_key: "your_api_key", email: "your@email.com", transaction_request_id: requestId }),
});
return res.json();
}
cURL Sample
Initiate STK Push
curl -X POST BASE/v1/stkpush \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key",
"email": "your@email.com",
"amount": "100",
"msisdn": "0712345678",
"reference": "ORDER-001"
}'
Check Transaction Status
curl -X POST BASE/v1/tstatus \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key",
"email": "your@email.com",
"transaction_request_id": "txn_k2m9x0q8w1e4r7t5y3u6"
}'
Subscription & Pricing
| Plan | Price | Notes |
|---|---|---|
| Monthly | KES 400 / month | Per linked account |
| Yearly | KES 4,000 / year | Per linked account. Save KES 800. |
Error Codes
| Code | Description |
|---|---|
0 | Success: transaction completed |
102 | Missing or invalid required parameter (e.g. api_key, email, msisdn) |
201 | Invalid HTTP method: use POST |
400 | Account inactive (no active subscription), disabled, or invalid account type |
429 | Too many requests. Limits: 120 STK pushes per minute per account, 5 prompts per phone number every 2 minutes, and repeated failed authentication from one IP is blocked for 15 minutes. Wait and retry (see the Retry-After header). |
503 | Server error or Safaricom API failure. Try again shortly. |
1 | Insufficient M-Pesa balance |
1032 | Transaction cancelled by user |
1037 | Timeout: user cannot be reached |
1025 | Error sending the push request |
1001 | Transaction already in process for this number, or duplicate request |
2001 | Invalid initiator information (often a wrong M-Pesa PIN) |
9001 | Customer paid less than the amount requested. The payment is marked failed and flagged for review; the M-Pesa receipt is kept so you can refund or collect the balance (see Late results) |

