● EXTERNAL SYSTEM INTERFACE (API V1)

M-Pesa Backend Gateway & API Engine

Integrate instant phone STK pushes, customer wallet deposits, and webhooks into any external shopping website or app

Authorized API Access Keys

Pass your key in HTTP headers: Authorization: Bearer <KEY>

POST /api/v1/payments/stk-push

API Test Playground

Simulate an external e-commerce call to your backend

Ready-To-Paste Integration Code

Drop this snippet directly into your shopping cart or backend service

curl -X POST "https://api.yourdomain.com/api/v1/payments/stk-push" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "phone": "0712345678",
    "amount": 100,
    "reference": "ORDER-101",
    "description": "Store Order",
    "webhook_url": "https://webhook.site/test"
  }'

Asynchronous Webhook Event Payload

When your customer enters their PIN, our backend immediately forwards this JSON payload to your webhook_url:

{
  "event": "mpesa.payment.completed",
  "checkout_request_id": "ws_CO_24102026...",
  "merchant_request_id": "b65b-47a4-...",
  "mpesa_receipt": "UJOR9AUAYR",
  "amount": 1200,
  "phone": "254712345678",
  "reference": "ORDER-101",
  "status": "COMPLETED",
  "result_code": 0,
  "result_desc": "The service request is processed successfully.",
  "timestamp": "2026-10-24T22:25:30.000Z"
}