STK Push (Accept Payments from Customers)

Trigger an instant M-Pesa payment prompt on your customer’s phone. The customer enters their PIN, and funds are transferred directly to our account for float updates.

Endpoint

POST /stk_push

Production
https://payments.pesavoucher.com/api/v1/stk_push

Sandbox
https://sandbox.payments.pesavoucher.com/api/v1/stk_push

Request Example

curl -X POST https://payments.pesavoucher.com/api/v1/stk_push \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "phone_number": "254708374149",
    "amount": 1250.00,
    "account_reference": "INV-2025-0891",
    "transaction_desc": "Premium Plan – Annual Subscription",
    "metadata": {
      "customer_id": "CUST-8871",
      "plan": "premium-annual"
    }
  }'

Request Parameters

Parameter	Type	Required	Description
`phone_number`	string	Yes	Customer phone in 254XXXXXXXXX format (auto-converts 07xx / +254)
`amount`	float	Yes	Exact amount with 2 decimal places
`account_reference`	string	Yes	Your internal invoice/order ID (max 12 chars recommended)
`transaction_desc`	string	Yes	Message shown to customer on their phone
`metadata`	object	No	Any custom data you want attached to the transaction

Amount Rules

Rule	Value
Minimum amount	`10.00` KES
Maximum per transaction	`150,000.00` KES
Decimal places	Exactly 2
Examples	`250.00`, `1099.50`

Phone Number Handling

Automatically accepted & converted:

254708374149 → recommended
0708374149
+254708374149
0718 374 149 (spaces ignored)

Invalid formats will return an error.

Success Response (Push Initiated)

{
  "success": true,
  "message": "STK push initiated successfully",
  "data": {
    "payment_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_request_id": "MERCHANT-20251120-001",
    "checkout_request_id": "ws_CO_20112025143022123",
    "customer_message": "Please check your phone and enter your PIN to complete payment",
    "amount": 1250.00,
    "phone_number": "254708374149"
  }
}

The final result is delivered via your webhook.

STK Push Webhook Callback (Final Result)

{
  "payment_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_request_id": "MERCHANT-20251120-001",
  "checkout_request_id": "ws_CO_20112025143022123",
  "status": "Success",
  "result_code": "0",
  "result_description": "The service request is processed successfully.",
  "initial_amount": 1250.00,
  "actual_amount": 1250.00,
  "mpesa_receipt_number": "SKL9P2M4XQ",
  "transaction_date": "20251120143245",
  "phone_number": "254708374149",
  "payer_phone": "254708374149",
  "payer_name": "JOHN DOE",
  "account_reference": "INV-2025-0891",
  "timestamp": "2025-11-20 14:32:50"
}

Status Values & Actions

Status	Meaning	Recommended Action
`Success`	Payment completed	Credit user account / fulfill order
`Failed`	Payment rejected	Show error, allow retry
`Cancelled`	User pressed Cancel	Allow retry
`Timeout`	User didn’t respond in time	Allow retry (common result_code: 1037)

Common Result Codes

Code	Description
`0`	Success
`1`	Insufficient balance
`1032`	Cancelled by user
`1037`	Timeout – no response
`2001`	Invalid credentials / account issue

Sandbox Test Phone Numbers

Phone Number	Behavior
`254708374149`	Always succeeds instantly
`254711223344`	Always fails (insufficient funds)
`254722334455`	User cancels
`254733445566`	Timeout (no response)

Rate Limits

60 requests per minute (default)
Burst up to 100/min
Higher limits available on request

You’re now ready to accept real-time mobile money payments though MPESA from customers!