Initiate MPESA STK Push

POST https://upesipay.com/api/v2/payments

Initiate an MPESA STK Push request to a customer's phone

Headers

Parameter	Type	Description
`Authorization`*	String	Basic auth token
`Content-Type`*	String	application/json

Request Body

Parameter	Type	Description
`amount`*	Integer	Payment amount (e.g., 100)
`phone_number`*	String	Customer phone number (e.g., 0787677677)
`channel_id`*	Integer	Your registered payment channel ID (e.g., 2133)
`provider`*	String	Value: m-pesa
`external_reference`	String	Your unique reference to track this transaction (e.g., INV-009)
`customer_name`	String	Customer name (Optional)
`callback_url`	String	Your endpoint URL for payment status response
`credential_id`	String	Optional: The ID of your registered credential for custom Mpesa Daraja integration

Responses

201 Created - Upon Successful Request

{
  "success": true,
  "status": "QUEUED",
  "reference": "E8UWT7CLUW",
  "CheckoutRequestID": "ws_CO_02012026164321519708344109"
}

Warning

STK Abuse Protection: If an account sends more than 10 successive failed or cancelled STK requests to the same phone number, that specific phone number will be blocked from receiving further STK push requests from the account for 24 hours. Other phone numbers on the account are not affected. Developers should avoid sending too many failed/cancelled requests to the same phone number in quick succession.
General Abuse Protection: If an account accumulates over 50 failed requests within a sliding window of 6 hours, the account will be restricted from sending further STK push requests for 4 hours. If this number reaches 500 within that window, the restriction is for 24 hours. At 1000 failed requests, the restriction increases to 72 hours. The strategy uses a sliding window and failed/cancelled requests are counted within a 6-hour window.

Notes

channel_id - Your wallet channel ID can be found under Payment Channels menu
provider - Use 'm-pesa' for MPESA channels

Try It Out

Please set your authentication token in the sidebar to test this API.

Code Samples

curl -X POST \
  'https://upesipay.com/api/v2/payments' \
  -H 'Authorization: Basic YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"amount":100,"phone_number":"0787677677","channel_id":2133,"provider":"m-pesa","external_reference":"INV-009","customer_name":"John Doe","callback_url":""}'

const url = 'https://upesipay.com/api/v2/payments';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "amount": 100,
  "phone_number": "0787677676",
  "channel_id": 133,
  "provider": "m-pesa",
  "external_reference": "INV-009",
  "customer_name": "John Doe",
  "callback_url": "https://example.com/callback.php"
})
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const axios = require('axios');

const config = {
  method: 'POST',
  url: 'https://upesipay.com/api/v2/payments',
  headers: {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json',
  }
,
  data: {
  "amount": 100,
  "phone_number": "0787677676",
  "channel_id": 133,
  "provider": "m-pesa",
  "external_reference": "INV-009",
  "customer_name": "John Doe",
  "callback_url": "https://example.com/callback.php"
}
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

import requests
import json

url = 'https://upesipay.com/api/v2/payments'

headers = {
    'Authorization': 'Basic YOUR_AUTH_TOKEN',
    'Content-Type': 'application/json',
}

payload = {
  "amount": 100,
  "phone_number": "0787677676",
  "channel_id": 133,
  "provider": "m-pesa",
  "external_reference": "INV-009",
  "customer_name": "John Doe",
  "callback_url": "https://example.com/callback.php"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://upesipay.com/api/v2/payments',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 100,
  "phone_number": "0787677676",
  "channel_id": 133,
  "provider": "m-pesa",
  "external_reference": "INV-009",
  "customer_name": "John Doe",
  "callback_url": "https://example.com/callback.php"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic YOUR_AUTH_TOKEN',
    'Content-Type: application/json',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

HttpClient client = HttpClient.newHttpClient();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
    .uri(URI.create("https://upesipay.com/api/v2/payments"))
    .post(BodyPublishers.ofString("{\"amount\":100,\"phone_number\":\"0787677676\",\"channel_id\":133,\"provider\":\"m-pesa\",\"external_reference\":\"INV-009\",\"customer_name\":\"John Doe\",\"callback_url\":\"https://example.com/callback.php\"}"));

requestBuilder.header("Authorization", "Basic YOUR_AUTH_TOKEN");
requestBuilder.header("Content-Type", "application/json");

HttpRequest request = requestBuilder.build();

try {
    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
    System.out.println(response.body());
} catch (Exception e) {
    e.printStackTrace();
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://upesipay.com/api/v2/payments"

    payload := map[string]interface{}{
        "amount": 100,
        "phone_number": "0787677676",
        "channel_id": 133,
        "provider": "m-pesa",
        "external_reference": "INV-009",
        "customer_name": "John Doe",
        "callback_url": "https://example.com/callback.php",
    }
    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))

    req.Header.Set("Authorization", "Basic YOUR_AUTH_TOKEN")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://upesipay.com/api/v2/payments')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)

request['Content-Type'] = 'application/json'
request['Authorization'] = 'Basic YOUR_AUTH_TOKEN'

request.body = '{"amount":100,"phone_number":"0787677676","channel_id":133,"provider":"m-pesa","external_reference":"INV-009","customer_name":"John Doe","callback_url":"https://example.com/callback.php"}'

response = http.request(request)
puts JSON.parse(response.body)

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();

        client.DefaultRequestHeaders.Add("Content-Type", "application/json");
        client.DefaultRequestHeaders.Add("Authorization", "Basic YOUR_AUTH_TOKEN");

        var request = new HttpRequestMessage(HttpMethod.POST, "https://upesipay.com/api/v2/payments");

        var json = JsonSerializer.Serialize(new {
            amount = 100,
            phone_number = "0787677676",
            channel_id = 133,
            provider = "m-pesa",
            external_reference = "INV-009",
            customer_name = "John Doe",
            callback_url = "https://example.com/callback.php"
        });
        request.Content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.SendAsync(request);
        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}

import Foundation

let url = URL(string: "https://upesipay.com/api/v2/payments")!
var request = URLRequest(url: url)
request.httpMethod = "POST"

request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("Basic YOUR_AUTH_TOKEN", forHTTPHeaderField: "Authorization")

let body: [String: Any] = [
    "amount": 100,
    "phone_number": "0787677676",
    "channel_id": 133,
    "provider": "m-pesa",
    "external_reference": "INV-009",
    "customer_name": "John Doe",
    "callback_url": "https://example.com/callback.php"
]
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        if let json = try? JSONSerialization.jsonObject(with: data) {
            print(json)
        }
    }
}
task.resume()

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException

val client = OkHttpClient()

val json = """{"amount":100,"phone_number":"0787677676","channel_id":133,"provider":"m-pesa","external_reference":"INV-009","customer_name":"John Doe","callback_url":"https://example.com/callback.php"}"""
val mediaType = "application/json".toMediaType()
val body = json.toRequestBody(mediaType)

val request = Request.Builder()
    .url("https://upesipay.com/api/v2/payments")
    .post(body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Authorization", "Basic YOUR_AUTH_TOKEN")
    .build()

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        e.printStackTrace()
    }

    override fun onResponse(call: Call, response: Response) {
        println(response.body?.string())
    }
})

Was this page helpful?

Learn how to get available bank paybills for channel registration.

Get Bank Paybills

Learn how to integrate payment buttons for simple payment collection.

Payment Button