Core API

STK Push API

Initiate M-Pesa payments directly to your customer's phone. Full API reference with examples.

Overview

STK Push initiates a payment request on the customer's phone. The customer receives a popup on their M-Pesa menu to authorize the payment.

Auto-Features

The /mpesa/payment/initiate endpoint automatically normalizes phone numbers and selects your default payment account. You only need to provide amount, phone, and optionally description.

Initiate Payment

Send a POST request to initiate an STK Push payment:

bash

curl -X POST "https://paynexus.co.ke/api/mpesa/payment/initiate" \
  -H "X-API-Key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phone": "0746990866",
    "description": "Order #12345"
  }'

Request Parameters

Field	Type	Required	Description
`amount`	integer	Yes	Payment amount in KES (minimum 1).
`phone`	string	Yes	Customer phone number. Auto-normalized (e.g. `0746990866` → `254746990866`).
`description`	string	No	Payment description shown to customer.

Response

A successful response returns a checkout_request_id to track the payment:

json

{
  "success": true,
  "data": {
    "reference": "PNXABC123DEF",
    "checkout_request_id": "ws_CO_27012026101718139746990866",
    "amount": 100,
    "phone": "254746990866",
    "status": "initiated"
  }
}

Check Payment Status

Check the status of a payment using its reference:

bash

curl -X GET "https://paynexus.co.ke/api/payments/PNXABC123DEF" \
  -H "X-API-Key: pk_your_public_key_here"

You can also check status by checkout request ID:

bash

curl -X POST "https://paynexus.co.ke/api/payments/status-by-checkout-id" \
  -H "X-API-Key: pk_your_public_key_here" \
  -H "Content-Type: application/json" \
  -d '{"checkout_request_id": "ws_CO_27012026101718139746990866"}'

Validate Phone Number

Validate and normalize phone numbers before initiating payments:

bash

curl -X POST "https://paynexus.co.ke/api/mpesa/validate-phone" \
  -H "X-API-Key: pk_your_public_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0746990866"}'

json

{
  "success": true,
  "data": {
    "original": "0746990866",
    "normalized": "254746990866",
    "valid": true,
    "provider": "mpesa"
  }
}

Status Values

Status	Description
`initiated`	STK Push sent to customer's phone
`processing`	Payment is being processed
`completed`	Payment successful
`failed`	Payment failed
`cancelled`	Customer cancelled the request
`expired`	STK Push request expired

Code Examples

javascript

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://paynexus.co.ke/api',
  headers: { 'X-API-Key': 'sk_your_secret_key_here' }
});

async function initiatePayment() {
  const response = await client.post('/mpesa/payment/initiate', {
    amount: 100,
    phone: '0746990866',
    description: 'Order #12345'
  });
  console.log(response.data);
}

initiatePayment();

php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => 'https://paynexus.co.ke/api/mpesa/payment/initiate',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: sk_your_secret_key_here',
    'Content-Type: application/json'
  ],
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 100,
    'phone' => '0746990866',
    'description' => 'Order #12345'
  ])
]);

$response = curl_exec($ch);
$payment = json_decode($response, true);
echo $payment['data']['reference'];

python

import requests

response = requests.post(
    'https://paynexus.co.ke/api/mpesa/payment/initiate',
    headers={'X-API-Key': 'sk_your_secret_key_here'},
    json={
        'amount': 100,
        'phone': '0746990866',
        'description': 'Order #12345'
    }
)

print(response.json())

Amount Limits

Environment	Minimum	Maximum
Production	1 KES	150,000 KES
Sandbox	1 KES	50 KES

Authentication

Payment Links