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

Authentication

Every request includes two credentials in the JSON body:

ParameterTypeDescription
api_keystringYour API key. Find it under Linked accounts → Manage. Each linked account has its own keys.
emailstringThe email address registered on your EQOPAY account
Security: keep your API key on your server. Never put it in client-side code (browser JavaScript or mobile apps). If a key is exposed, revoke it in the dashboard and create a new one.

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

  1. Create an account at eqopay.co.ke and log in.
  2. Link a payment account: your Till number, Paybill number, or bank paybill and account number.
  3. Activate it with a subscription paid by M-Pesa from the dashboard (see Subscription & Pricing).
  4. Make your first API call to /v1/stkpush with your api_key and email.

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.

ParameterTypeRequiredDescription
api_keystringYesYour API key
emailstringYesYour registered email
amountstringYesAmount in KES (whole shillings, minimum 1)
msisdnstringYesCustomer phone, e.g. 0712345678 or 254712345678
referencestringYesPayment reference or description, e.g. an order number
account_numberstringOptionalRequired 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.

ParameterTypeRequiredDescription
api_keystringYesYour API key
emailstringYesYour registered email
transaction_request_idstringYesThe 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"
}
Tip: 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:

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:

PhoneSimulated outcome
254700000001Failed: insufficient balance
254700000002Cancelled by the customer
254700000003Expired: customer didn't respond
254700000004Failed: initiator error
254700000005Expires first, then a late success arrives (two webhooks; flagged for review)
254700000006Customer 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.

  1. Link your Till, Paybill or bank account in the dashboard.
  2. Activate the account with a subscription.
  3. Copy your payment page link from Linked accounts and share it.
  4. 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 typeCustomer entersDescription
Till NumberPhone, amountLipa Na M-Pesa Buy Goods. Money goes straight into your till.
PaybillPhone, amount, account numberThe customer supplies the account number. Money goes straight into your paybill.
Bank AccountPhone, amountPaid through your bank's M-Pesa paybill. Your account number is preset when you link the account, so money goes straight into your bank.
Note: you can link several accounts under one EQOPAY user. Each account has its own API key and payment page.

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

PlanPriceNotes
MonthlyKES 400 / monthPer linked account
YearlyKES 4,000 / yearPer linked account. Save KES 800.
Activation: pay for your plan with M-Pesa from the dashboard under Billing. The account is activated as soon as the payment is confirmed. EQOPAY charges no per-transaction fees.

Error Codes

CodeDescription
0Success: transaction completed
102Missing or invalid required parameter (e.g. api_key, email, msisdn)
201Invalid HTTP method: use POST
400Account inactive (no active subscription), disabled, or invalid account type
429Too 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).
503Server error or Safaricom API failure. Try again shortly.
1Insufficient M-Pesa balance
1032Transaction cancelled by user
1037Timeout: user cannot be reached
1025Error sending the push request
1001Transaction already in process for this number, or duplicate request
2001Invalid initiator information (often a wrong M-Pesa PIN)
9001Customer 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)