📳POST: Send Customer MPESA STK

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

Integrate your MPESA Till Number, Paybill Number, or Bank Account seamlessly with Pay Hero to streamline automated payments and centralize payment tracking. Pay Hero offers a sophisticated API and aggregation service designed to enhance efficiency across diverse payment channels, positioning itself as the preferred solution for businesses and individuals seeking a comprehensive payment management system.

API Method

This endpoint enables you to initiate an MPESA STK Push request to get paid to your linked payment channel.

POST https://backend.payhero.co.ke/api/v2/payments

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 Account section, Payment channels.
provider*	String	Value: m-pesa
external_reference	String	Your unique reference to track this transaction Eg: INV-009
callback_url	String	Your endpoint URL that we will use to send payment status response eg: https://example.com/callback.php

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

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

Sample Code

This represents PHP Curl example of how to make the request, you can implement this in your specific language of choice

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://backend.payhero.co.ke/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": 10,
    "phone_number": "0798766765",
    "channel_id": 911, 
    "provider": "m-pesa", 
    "external_reference": "INV-009",
    "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;

Callback URL Response Sample

This represents the JSON that will be sent to your request callback_url, NOTE: it contains the ExternalReference that you provided in the request and CheckoutRequestID that was returned in the request response, you can use those to track and update your payments in your system/app

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