← Back to API Home

M-Pesa API Documentation

Note: All initiator endpoints require an Authorization header.
Format: Authorization: Bearer <your_jwt_token>

1. STK PUSH (Lipa na M-Pesa Online)

Endpoint: POST /api/mpesa/stkpush

Body (JSON):

{
  "phone": "07xxxxxxxx",      // Required. Can be 07... or 2547...
  "amount": 1,                // Required. Integer.
  "reference": "Order #123",  // Optional. Account Reference.
  "description": "Payment"    // Optional.
}

Response: Success initiates an STK prompt on the user's phone. Callback sent to MPESA_CALLBACK_URL.

2. STK PUSH QUERY (Check Payment Status)

Endpoint: POST /api/mpesa/stkquery

Body (JSON):

{
  "checkoutRequestId": "ws_CO_1234567890"  // Required. Received from STK Push response
}

Response: Payment status from Safaricom (e.g. 0 for success, 1032 for cancelled).

3. B2C (Business to Customer)

Endpoint: POST /api/mpesa/b2c

Body (JSON):

{
  "phone": "07xxxxxxxx",      // Required.
  "amount": 100,              // Required. Integer.
  "commandId": "BusinessPayment", // Optional. Defaults to BusinessPayment
  "remarks": "Refund",        // Optional.
  "occasion": ""              // Optional.
}

Response: Request acknowledgment. Callbacks sent to MPESA_B2C_RESULT_URL and MPESA_B2C_TIMEOUT_URL.

Webhook Callbacks

The following public endpoints are used to receive automated callbacks from Daraja: