Send STK Push requests to customer phones and process M-Pesa payments seamlessly through our API.

The initiate endpoint handles payment requests, validates parameters, and returns immediate responses with tracking information.

Endpoint Details

  1. Endpoint URL

    POST request to initiate M-Pesa STK Push payments. Payments are sent to your onboarded shortcode.

    POST https://felixdev.io/api/v1/initiate

  2. Rate Limiting

    API requests are rate limited to prevent abuse and ensure system stability for all users.

    Rate Limits:
    • 30 requests per minute per API key
    • 60 requests per minute for status checks
    • Rate limit headers included in responses
    • HTTP 429 returned when limit exceeded
  3. Request Parameters

Request Parameters

  1. Required Headers

    Authentication headers that must be included with every request.

    Headers:
    apikey: your_api_key_here
    linkid: your_shortcode_tracking_code
    Content-Type: application/json

  2. JSON Body Parameters

    Request body parameters for payment initiation.

    { "msisdn": "254712345678", "amount": 100, "callback": "https://yoursite.com/webhook" }

  3. Parameter Validation

    All parameters are validated for format, range, and accessibility.

    Validation Rules:
    • msisdn: Must be 254XXXXXXXXX format
    • amount: Integer between 1 and 300,000
    • callback: Valid HTTPS URL (production)
    • callback: Accessible endpoint (tested)
  4. Response Format

Response Format

  1. Success Response

    Response format for successful payment initiation.

    { "success": true, "request_id": "REQ_abc123def456", "checkout_request_id": "ws_CO_27072023123456789", "merchant_request_id": "29115-34620561-1", "status": "pending", "message": "STK Push sent successfully", "customer_message": "Success. Request accepted for processing" }

  2. Error Response

    Response format for failed requests with detailed error information.

    { "success": false, "error": "INVALID_API_KEY", "message": "Invalid API key provided", "request_id": null }

  3. Complete cURL Example

    Full cURL command for testing the API endpoint.

    curl -X POST https://felixdev.io/api/v1/initiate \ -H "Content-Type: application/json" \ -H "apikey: pk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t" \ -H "linkid: sc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4" \ -d '{ "msisdn": "254712345678", "amount": 100, "callback": "https://yoursite.com/webhook" }'
  4. Webhook Setup