UMS Pay API Documentation

Your credentials — where to find them

Every API call needs three merchant identifiers. Log in at umspay.co.ke to collect them.

Before going live: your connected account must be active (paid plan or trial). Set your webhook URL per account under Webhook Settings.

Quick start

1. Create a free account at umspay.co.ke/register
2. Connect a Paybill, Till, or Bank account under Connected Accounts
3. Activate the account (subscription or 3-day trial)
4. Generate your API key in Account Settings
5. POST to /api/v1/initiatestkpush — customer gets M-Pesa prompt on phone
6. Confirm payment via webhook or transaction status API

Minimal cURL example

curl -X POST https://api.umspay.co.ke/api/v1/initiatestkpush \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "UMPAY_your_key_here",
    "email": "[email protected]",
    "amount": 100,
    "msisdn": "254712345678",
    "reference": "ORDER-1001",
    "account_id": "UMSPAY1234567890"
  }'

Payment flow

Save the transaction_request_id from the STK response. Use it to poll status or match incoming webhooks. Your custom reference is echoed back in status and webhook payloads.

Initiate STK Push

Sends an M-Pesa STK push to the customer's phone. Amount is in KES. Phone must be Kenyan format 2547XXXXXXXX (leading 0 is also accepted and normalized).

Request body (JSON)

Code examples

curl -X POST https://api.umspay.co.ke/api/v1/initiatestkpush \
  -H "Content-Type: application/json" \
  -d '{"api_key":"UMPAY_xxx","email":"[email protected]","amount":500,"msisdn":"254712345678","reference":"INV-42","account_id":"UMSPAY1234567890"}'

$payload = [
    'api_key'    => getenv('UMSPAY_API_KEY'),
    'email'      => getenv('UMSPAY_EMAIL'),
    'amount'     => 500,
    'msisdn'     => '254712345678',
    'reference'  => 'INV-' . time(),
    'account_id' => getenv('UMSPAY_ACCOUNT_ID'),
];
$ch = curl_init('https://api.umspay.co.ke/api/v1/initiatestkpush');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
// Save $response['transaction_request_id']

const res = await fetch('https://api.umspay.co.ke/api/v1/initiatestkpush', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.UMSPAY_API_KEY,
    email: '[email protected]',
    amount: 500,
    msisdn: '254712345678',
    reference: 'INV-' + Date.now(),
    account_id: 'UMSPAY1234567890',
  }),
});
const data = await res.json();
console.log(data.transaction_request_id);

{
  "success": "200",
  "message": "Request processed successfully",
  "transaction_request_id": "UMSPID1507202610231492867"
}

{
  "ResultCode": "403",
  "errorMessage": "Your subscription has expired. Please subscribe to continue using UMS Pay services.",
  "subscription_required": true
}

Check transaction status

Poll payment result using the transaction_request_id from STK Push. For pending payments, UMS Pay may query Safaricom live before returning status.

{
  "ResultCode": "200",
  "ResultDesc": "Success. Request accepted for processing",
  "TransactionID": "UMSPID1507202610231492867",
  "TransactionAccountID": "UMSPAY1234567890",
  "TransactionStatus": "Completed",
  "TransactionCode": "0",
  "TransactionReceipt": "THF123ABC",
  "TransactionAmount": "500",
  "Msisdn": "254712345678",
  "TransactionDate": "07/15/26 10:23 AM",
  "TransactionReference": "INV-42",
  "MpesaResponse": "{...}"
}

Transaction status values

Transaction status (v2)

Same parameters as v1. Returns structured HTTP status codes and a lighter JSON shape — recommended for new integrations.

Free trial (3 days)

New merchants with a single connected account can start a 3-day API trial before subscribing.

Returns trial_eligible, trial_active, trial_days_remaining, and trial dates.

Webhooks

Configure a webhook URL per connected account in Webhook Settings. When a payment completes or fails, UMS Pay sends a POST request with JSON body to your URL.

Webhook payload

{
  "ResponseCode": 0,
  "ResponseDescription": "Success. Request accepted for processing",
  "MerchantRequestID": "xxx",
  "CheckoutRequestID": "ws_CO_xxx",
  "TransactionID": "UMSPID1507202610231492867",
  "TransactionAmount": 500,
  "TransactionReceipt": "THF123ABC",
  "TransactionDate": "20260715102333",
  "TransactionReference": "INV-42",
  "Msisdn": "254712345678"
}

• ResponseCode 0 = success; other codes = failure/cancel (see error table)
• TransactionReference = your original reference from STK Push
• TransactionReceipt = M-Pesa confirmation code (may be empty until confirmed)
• Respond with HTTP 200 quickly; retry logic is on our side if delivery fails

Tip: Use webhooks as primary confirmation; use transaction status API as backup polling.

Error codes & rate limits

Rate limits (STK Push)

• 30 seconds cooldown per phone + account (duplicate STK protection)
• 3 requests/minute per account
• 40 requests/hour per account

High-risk patterns may be blocked automatically (fraud detection). Contact support if legitimate traffic is blocked.

Connected account types

When you connect an account at Connected Accounts, STK funds route based on type:

Each connected account needs an active subscription or trial. Account ID is required on every STK request via account_id.

Ready to test?

Use the dashboard test tool or download plugins for WooCommerce and custom apps.