API Documentation

Integrate M-Pesa STK Push payments into your application with our powerful and developer-friendly API.

Version:
v1
Base URL:https://api.pexmon.one/api/mpesa

Overview

The M-Pesa STK Push API allows you to integrate M-Pesa payment functionality into your applications. This API enables you to initiate payment requests, check transaction status, and handle payment callbacks.

Key Features

  • Initiate STK Push payments to customer phones
  • Query transaction status in real-time
  • Receive automated webhook notifications
  • Secure API key authentication

Authentication

Our API uses API keys to authenticate requests. All API requests must be made over HTTPS and include your secret API key in the x-api-key HTTP header.

Header Format

http
x-api-key: YOUR_API_KEY
Note: You can get your API key by logging into your account dashboard and navigating to the API Keys section.

POST
/stkPush

Initiates a new M-Pesa STK push payment request.

Request Body

ParameterTypeDescription
amountnumberThe amount to be charged.
phoneNumberstringThe customer's phone number in 254... format.
accountIdstringYour internal transaction reference number.

Example Request

curl -X POST https://api.pexmon.one/api/mpesa/stkPush \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "amount": 100,
    "phoneNumber": "254712345678",
    "accountId": "ACC123456"
  }'

Success Response

json
{
  "success": true,
  "message": "STK push initiated successfully",
  "data": {
    "MerchantRequestID": "29115-34620561-1",
    "CheckoutRequestID": "ws_CO_191220191020363925",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing"
  }
}

POST
/check-status

Query the status of a transaction using its CheckoutRequestID.

Request Body

json
{
  "checkoutRequestId": "ws_CO_191220191020363925"
}

Success Response

json
{
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "ResponseCode": "0",
    "CheckoutRequestID": "ws_CO_191220191020363925",
    "ResultCode": "0",
    "ResultDesc": "The service request is processed successfully."
  }
}

Handling Webhook Responses

After a transaction concludes, our server sends the final status to your configured webhook URL.

This is an asynchronous POST request that provides the final outcome of the transaction (e.g., success, user cancelled, insufficient funds). Your endpoint should be prepared to receive this data.

Example Successful Payment Callback

json
{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "1409-80154031-1",
      "CheckoutRequestID": "ws_CO_17072024110329432712345678",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 1.00 },
          { "Name": "MpesaReceiptNumber", "Value": "SGF123ABC4" },
          { "Name": "TransactionDate", "Value": 20240717110339 },
          { "Name": "PhoneNumber", "Value": 254712345678 }
        ]
      }
    }
  }
}

Result Codes

The ResultCode indicates the outcome of the transaction.

CodeDescriptionStatus
0
Request successfulSuccess
1
Insufficient balanceFailure
1032
Cancelled by userFailure
1037
Timeout waiting for responseFailure
2001
Invalid password (PIN)Failure