UMS Pay API Documentation

Integrate M-Pesa payments into your applications with our powerful and secure API endpoints

POST

Initiate STK Push Payment

https://api.umspay.co.ke/api/v1/initiatestkpush

Initiates an M-Pesa STK push payment request to the customer's phone. This endpoint requires a valid API key and an active UMS Pay account.

Request Parameters

Parameter Type Required Description
api_key string Yes Your unique API key for authentication
email string Yes Your registered UMS Pay account email
amount numeric Yes Transaction amount (minimum 10 KES)
msisdn string Yes Customer phone number in format 2547XXXXXXXX
reference string Yes Unique transaction reference for your records
account_id string Yes Your UMS Pay account ID

Example Request

{
  "api_key": "your_api_key_here",
  "email": "[email protected]",
  "amount": 1500,
  "msisdn": "254712345678",
  "reference": "ORDER-12345",
  "account_id": "ACC-7890"
}

Response

Success 200 Transaction initiated successfully 
{
  "success": "200",
  "message": "Request processed successfully",
  "transaction_request_id": "UMSPID2306202515304598765"
}
Error 400 Account inactive 
{
  "ResultCode": "400",
  "errorMessage": "Your UMS Pay account is not active! Activate your account by paying the subscription fee of Ksh 500"
}
POST

Check Transaction Status

https://api.umspay.co.ke/api/v1/transactionstatus

Retrieves the status of a previously initiated payment transaction. Use this to check payment completion, failure, or pending status.

Request Parameters

Parameter Type Required Description
api_key string Yes Your unique API key for authentication
email string Yes Your registered UMS Pay account email
transaction_request_id string Yes Transaction ID received from initiateStkPush response

Example Request

{
  "api_key": "your_api_key_here",
  "email": "[email protected]",
  "transaction_request_id": "UMSPID2306202515304598765"
}

Response

Success 200 Transaction completed 
{
  "ResultCode": "200",
  "ResultDesc": "Success",
  "TransactionID": "UMSPID2306202515304598765",
  "TransactionAccountID": "ACC-7890",
  "TransactionStatus": "Completed",
  "TransactionCode": "0",
  "TransactionReceipt": "REC12345",
  "TransactionAmount": "1500",
  "Msisdn": "254712345678",
  "TransactionDate": "06/23/24 03:30 PM",
  "TransactionReference": "ORDER-12345",
  "MpesaResponse": "{...raw M-Pesa response...}"
}
Error 400 Transaction not found 
{
  "ResultCode": "400",
  "errorMessage": "Transaction with id UMSPID2306202515304598765 does not exist!"
}

Transaction Status Codes

Status Code Description
Completed 0 Payment successful
Failed 1 Insufficient balance
Cancelled 1032 User cancelled payment
Timeout 1037 DS timeout - user not reachable
Pending Pending Awaiting user action

Authentication

All API requests require authentication using your API key. You can find your API key in your UMS Pay account dashboard under API Settings.

Include your API key in the api_key parameter with every request.

Rate Limits

To ensure service stability, we enforce the following rate limits:

  • 10 requests per second per API key
  • 5,000 requests per day per API key

If you exceed these limits, you'll receive a 429 Too Many Requests response.

Webhooks

For real-time payment notifications, we recommend setting up webhooks. Configure your webhook URL in your UMS Pay dashboard to receive instant payment status updates.

Webhook events include:

  • payment.initiated - When a payment request is created
  • payment.completed - When payment is successfully processed
  • payment.failed - When payment fails or is cancelled