DarajaPay

POST: Initiate MPESA STK Push Payment Request

This endpoint enables you to initiate an MPESA STK Push request to a customer number to receive payments to your linked payment channel

Easily initiate an MPESA STK Push request to a customer's phone, facilitating seamless mobile payments. You can link your own Till Number, Pay bill Number or Bank Account. By using this endpoint, you can automate payment requests, streamline the payment process, and easily track transactions through DarajaPay's centralized system. This feature is designed to enhance payment efficiency for businesses and individuals using MPESA services.

API Method

POST https://darajapay.com/api/v1/mpesa/stkpush

Headers

Name	Type	Description
Authorization:*	String	Basic basicAuthToken

Request Body

Name	Type	Description
amount*	Integer	Eg: 100
phone_number*	String	Eg: 0787677676
channel_id*	Integer	Your registered payment channel ID eg: 133 Can be found by logging in, under the Payment Channels menu, then My Payment Channels.
provider*	String	Value: m-pesa
external_reference	String	Your unique reference to track this transaction Eg: INV-009
customer_name	String	Customer name : Optional
callback_url	String	Your endpoint URL that we will use to send payment status response eg: https://example.com/callback.php

Response

201: Created Upon successful request, you will get below JSON response

JSON

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

Code Examples

PHP

 'https://darajapay.com/api/v1/mpesa/stkpush/',
  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": 10,
    "phone_number": "0798766765",
    "channel_id": 911, 
    "provider": "m-pesa", 
    "external_reference": "INV-009",
    "customer_name":"John Doe",
    "callback_url": "https://example.com/callback.php"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic 3A6anVoWFZrRk5qSVl0MGNMOERGMlR3dlhrQ0VWUWJHNDVVVnNaMEdDSw=='
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

Python

import requests

url = "https://darajapay.com/api/v1/mpesa/stk-push"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic 3A6anVoWFZrRk5qSVl0MGNMOERGMlR3dlhrQ0VWUWJHNDVVVnNaMEdDSw=="
}
data = {
    "amount": 10,
    "phone_number": "0798766765",
    "channel_id": 911,
    "provider": "m-pesa",
    "external_reference": "INV-009",
    "customer_name": "John Doe",
    "callback_url": "https://example.com/callback.php"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Node.js

const axios = require('axios');

const data = {
    amount: 10,
    phone_number: '0798766765',
    channel_id: 911,
    provider: 'm-pesa',
    external_reference: 'INV-009',
    customer_name: 'John Doe',
    callback_url: 'https://example.com/callback.php'
};

const config = {
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic 3A6anVoWFZrRk5qSVl0MGNMOERGMlR3dlhrQ0VWUWJHNDVVVnNaMEdDSw=='
    }
};

axios.post('https://darajapay.com/api/v1/mpesa/stk-push', data, config)
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

Java

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

public class MPESAExample {
    public static void main(String[] args) {
        String url = "https://darajapay.com/api/v1/mpesa/stk-push";
        String requestBody = """
            {
                "phone": "254712345678",
                "amount": 100,
                "reference": "INV001",
                "callback_url": "https://your-domain.com/callback"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("Authorization", "Basic YOUR_API_KEY")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
            .thenApply(HttpResponse::body)
            .thenAccept(System.out::println)
            .join();
    }
}

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();
        var url = "https://darajapay.com/api/v1/mpesa/stk-push";
        
        var data = new
        {
            phone = "254712345678",
            amount = 100,
            reference = "INV001",
            callback_url = "https://your-domain.com/callback"
        };

        client.DefaultRequestHeaders.Add("Authorization", "Basic YOUR_API_KEY");
        
        var json = JsonSerializer.Serialize(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync(url, content);
        var result = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine(result);
    }
}

package main

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

func main() {
    url := "https://darajapay.com/api/v1/mpesa/stk-push"
    data := map[string]interface{}{
        "phone": "254712345678",
        "amount": 100,
        "reference": "INV001",
        "callback_url": "https://your-domain.com/callback",
    }

    jsonData, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Basic YOUR_API_KEY")

    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)
}

Ruby

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

url = URI("https://darajapay.com/api/v1/mpesa/stk-push")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Basic YOUR_API_KEY"

request.body = {
  phone: "254712345678",
  amount: 100,
  reference: "INV001",
  callback_url: "https://your-domain.com/callback"
}.to_json

response = http.request(request)
puts response.read_body

Callback URL Response Sample

This represents the JSON that will be sent to your request callback_url. It contains the ExternalReference that you provided in the request and CheckoutRequestID that was returned in the request response. You can use these to track and update your payments in your system/app.

JSON

{
  "forward_url": "",
  "response": {
    "Amount": 10,
    "CheckoutRequestID": "ws_CO_14012024103543427709099876",
    "ExternalReference": "INV-009",
    "MerchantRequestID": "3202-70921557-1",
    "MpesaReceiptNumber": "SAE3YULR0Y",
    "Phone": "+254709099876",
    "ResultCode": 0,
    "ResultDesc": "The service request is processed successfully.",
    "Status": "Success"
  },
  "status": true
}

POST: Service Wallet Top Up Payment Button