Initiate Payment

Requirements

Triggering stk push requires you to have the following:

  • Api Key e.g YTFCV55
  • Link Id e.g #PYSCLRTXF

{info} But for test while intergrating you can use the sandbox credentials

Request Parameters

Request Type

Method Endpoint
POST http://ecvps.net/api/v1/initiate

Request Headers

parameter TYPE Description
ApiKey string Api Key used to authenticate your app(s) requests
LinkId string Unique Link Id to identify the payments Settlment Link

Request Body

parameter TYPE Description
msisdn string (required) Subscriber's phone number in this format 2547xxxxxx
amount integer (required) Amount To Be Requested From The subscriber msisd
callback string (Optional) link to receive Realtime payment notification(s)

Responses

Sucess response

{success} Successful request sample response.

{
    "MerchantRequestID": "92974-45072677-1",
    "CheckoutRequestID": "ws_CO_03122023035229721110156957",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing",
    "CustomerMessage": "Success. Request accepted for processing"
}

Validation Errors

{warning} Validation Errors.

{
    "errors": {
        "msisdn": [
            "MSISDN is required in the request body.",
            "Invalid MSISDN format. It should be in the format 254xxxxxxx and have a maximum of 12 characters."
        ],
        "amount": ["Amount Available is required in the request body."],
        "callback": ["The callback field is required."]
    }
}

Unsuccesful Request

{danger} Unsuccessful Authentication request sample response.

{
    "errors": {
    "apikey": [
        "The apikey field is required."
    ],
    "linkId": [
        "The link id field is required."
    ]
    }
}

//invalid credentials

{
    "errors": {
    "ApiCredentials": "invalid api credentials"
    }
}

Example Codes

Javascript axios example

import axios from "axios";

const options = {
    method: "POST",
    url: "https://payscel.com/api/v1/initiate",
    headers: {
        "Content-Type": "application/json",
        "User-Agent": "insomnia/2023.5.8",
        apikey: "yourApikey",
        linkid: "YourLinkId",
    },
    data: {
        msisdn: 2547xxxxxxxx,
        amount: 20,
        callback: "http://exmple.com/callback",
    },
};

axios
    .request(options)
    .then(function (response) {
        console.log(response.data);
    })
    .catch(function (error) {
        console.error(error);
    });

php curl example


<?php

    $curl = curl_init();

    $data = [
        "msisdn" => 2547xxxxxxxx,
        "amount" => 20,
        "callback" => "http://example.com/callback"
    ];

    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://payscel.com/api/v1/initiate',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            "Content-Type: application/json",
            "User-Agent: insomnia/2023.5.8",
            "apikey: aba6262200b0",
            "linkid: #PYSCL5b"
        ],
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
        echo "cURL Error #:" . $err;
    } else {
        echo $response;
}
?>