curl --request POST \
  --url https://api.staging.kairosafrika.cloud/paygw/v1/payment \
  --header 'Authorization: Basic $(echo -n "username:password" | base64)' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1,
    "referenceNo": "889909909229",
    "payee": "Kairos",
    "narration": "PIZZAMAN/CHICKMAN",
    "msisdn": "233559400612",
    "callbackId": "6607c05155dfd4919c18c44",
    "payer": "testOne"
  }'

const username = 'your_username';
const password = 'your_password';
const credentials = btoa(`${username}:${password}`);

const response = await fetch('https://api.staging.kairosafrika.cloud/paygw/v1/payment', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1,
    referenceNo: '889909909229',
    payee: 'Kairos',
    narration: 'PIZZAMAN/CHICKMAN',
    msisdn: '233559400612',
    callbackId: '6607c05155dfd4919c18c44',
    payer: 'testOne'
  })
});

const result = await response.json();
console.log(result);

import requests
import base64

username = 'your_username'
password = 'your_password'
credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

response = requests.post(
    'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 1,
        'referenceNo': '889909909229',
        'payee': 'Kairos',
        'narration': 'PIZZAMAN/CHICKMAN',
        'msisdn': '233559400612',
        'callbackId': '6607c05155dfd4919c18c44',
        'payer': 'testOne'
    }
)

result = response.json()
print(result)

<?php
$username = 'your_username';
$password = 'your_password';
$credentials = base64_encode($username . ':' . $password);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
  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 => json_encode(array(
    'amount' => 1,
    'referenceNo' => '889909909229',
    'payee' => 'Kairos',
    'narration' => 'PIZZAMAN/CHICKMAN',
    'msisdn' => '233559400612',
    'callbackId' => '6607c05155dfd4919c18c44',
    'payer' => 'testOne'
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
  ),
));

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

{
  "statusCode": "0001",
  "statusMessage": "PENDING",
  "transactionId": "20416369453214532143",
  "data": {
    "totalAmount": 45.68,
    "amount": 45,
    "charge": 0.68,
    "referenceId": "20416369453214532143"
  },
  "links": [
    {
      "rel": "self",
      "href": "/payment"
    }
  ]
}

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "The customer has insufficient funds for this transaction",
  "details": {}
}

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "The customer has insufficient funds for this transaction",
  "details": {}
}

POST

payment

curl --request POST \
  --url https://api.staging.kairosafrika.cloud/paygw/v1/payment \
  --header 'Authorization: Basic $(echo -n "username:password" | base64)' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1,
    "referenceNo": "889909909229",
    "payee": "Kairos",
    "narration": "PIZZAMAN/CHICKMAN",
    "msisdn": "233559400612",
    "callbackId": "6607c05155dfd4919c18c44",
    "payer": "testOne"
  }'

const username = 'your_username';
const password = 'your_password';
const credentials = btoa(`${username}:${password}`);

const response = await fetch('https://api.staging.kairosafrika.cloud/paygw/v1/payment', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1,
    referenceNo: '889909909229',
    payee: 'Kairos',
    narration: 'PIZZAMAN/CHICKMAN',
    msisdn: '233559400612',
    callbackId: '6607c05155dfd4919c18c44',
    payer: 'testOne'
  })
});

const result = await response.json();
console.log(result);

import requests
import base64

username = 'your_username'
password = 'your_password'
credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

response = requests.post(
    'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 1,
        'referenceNo': '889909909229',
        'payee': 'Kairos',
        'narration': 'PIZZAMAN/CHICKMAN',
        'msisdn': '233559400612',
        'callbackId': '6607c05155dfd4919c18c44',
        'payer': 'testOne'
    }
)

result = response.json()
print(result)

<?php
$username = 'your_username';
$password = 'your_password';
$credentials = base64_encode($username . ':' . $password);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
  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 => json_encode(array(
    'amount' => 1,
    'referenceNo' => '889909909229',
    'payee' => 'Kairos',
    'narration' => 'PIZZAMAN/CHICKMAN',
    'msisdn' => '233559400612',
    'callbackId' => '6607c05155dfd4919c18c44',
    'payer' => 'testOne'
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
  ),
));

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

{
  "statusCode": "0001",
  "statusMessage": "PENDING",
  "transactionId": "20416369453214532143",
  "data": {
    "totalAmount": 45.68,
    "amount": 45,
    "charge": 0.68,
    "referenceId": "20416369453214532143"
  },
  "links": [
    {
      "rel": "self",
      "href": "/payment"
    }
  ]
}

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "The customer has insufficient funds for this transaction",
  "details": {}
}

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "The customer has insufficient funds for this transaction",
  "details": {}
}

Initiate Payment

This endpoint allows you to initiate a new payment transaction. Endpoint: POST /v1/payment

curl --request POST \
  --url https://api.staging.kairosafrika.cloud/paygw/v1/payment \
  --header 'Authorization: Basic $(echo -n "username:password" | base64)' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1,
    "referenceNo": "889909909229",
    "payee": "Kairos",
    "narration": "PIZZAMAN/CHICKMAN",
    "msisdn": "233559400612",
    "callbackId": "6607c05155dfd4919c18c44",
    "payer": "testOne"
  }'

const username = 'your_username';
const password = 'your_password';
const credentials = btoa(`${username}:${password}`);

const response = await fetch('https://api.staging.kairosafrika.cloud/paygw/v1/payment', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1,
    referenceNo: '889909909229',
    payee: 'Kairos',
    narration: 'PIZZAMAN/CHICKMAN',
    msisdn: '233559400612',
    callbackId: '6607c05155dfd4919c18c44',
    payer: 'testOne'
  })
});

const result = await response.json();
console.log(result);

import requests
import base64

username = 'your_username'
password = 'your_password'
credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

response = requests.post(
    'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 1,
        'referenceNo': '889909909229',
        'payee': 'Kairos',
        'narration': 'PIZZAMAN/CHICKMAN',
        'msisdn': '233559400612',
        'callbackId': '6607c05155dfd4919c18c44',
        'payer': 'testOne'
    }
)

result = response.json()
print(result)

<?php
$username = 'your_username';
$password = 'your_password';
$credentials = base64_encode($username . ':' . $password);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.staging.kairosafrika.cloud/paygw/v1/payment',
  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 => json_encode(array(
    'amount' => 1,
    'referenceNo' => '889909909229',
    'payee' => 'Kairos',
    'narration' => 'PIZZAMAN/CHICKMAN',
    'msisdn' => '233559400612',
    'callbackId' => '6607c05155dfd4919c18c44',
    'payer' => 'testOne'
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
  ),
));

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

Request Body

amount (number, required): The payment amount.
referenceNo (string, required): Reference number for the payment.
payee (string, required): Name of the payee receiving the payment.
narration (string, required): Payment description or narration.
msisdn (string, required): Msisdn identifier for the payment.
callbackId (string, required): Callback identifier for payment status updates.
payer (string, required): Name or identifier of the payer.

Responses

200 OK - Payment Initiated Successfully

{
    "statusCode": "0001",
    "statusMessage": "PENDING",
    "transactionId": "20416369453214532143",
    "data": {
        "totalAmount": 45.68,
        "amount": 45,
        "charge": 0.68,
        "referenceId": "20416369453214532143"
    },
    "links": [
        {
            "rel": "self",
            "href": "/payment"
        }
    ]
}

400 Bad Request - Invalid Request Data

{
    "statusCode": "0400",
    "statusMessage": "Bad Request",
    "transactionId": null,
    "data": null,
    "links": []
}

401 Unauthorized - Invalid Credentials

{
    "statusCode": "0401",
    "statusMessage": "Unauthorized",
    "transactionId": null,
    "data": null,
    "links": []
}

Response Fields

statusCode (string): Status code indicating the result of the payment initiation
- "0001": Payment pending
- "0400": Bad request
- "0401": Unauthorized
statusMessage (string): Human-readable status message
transactionId (string): Unique transaction identifier for tracking
data (object): Payment details when successful
- totalAmount (number): Total amount including charges
- amount (number): Base payment amount
- charge (number): Processing charge amount
- referenceId (string): Reference identifier for the payment
links (array): HATEOAS links for related actions
- rel (string): Relationship type
- href (string): Link URL

Authorizations

Authorization

string

header

required

Basic authentication using base64 encoded username:password

Body

application/json

amount

number

required

Payment amount

Example:

1

referenceNo

string

required

Reference number for the payment

Example:

"889909909229"

payee

string

required

Name of the payee receiving the payment

Example:

"Kairos"

narration

string

required

Payment description or narration

Example:

"PIZZAMAN/CHICKMAN"

msisdn

string

required

Msisdn identifier for the payment

Example:

"233559400612"

callbackId

string

required

Callback identifier for payment status updates

Example:

"6607c05155dfd4919c18c44"

payer

string

required

Name or identifier of the payer

Example:

"testOne"

Response

Payment initiated successfully

statusCode

string

Status code indicating the result of the payment initiation

Example:

"0001"

statusMessage

string

Human-readable status message

Example:

"PENDING"

transactionId

string

Unique transaction identifier for tracking

Example:

"20416369453214532143"

data

object | null

Payment details when successful

Show child attributes

links

object[]

HATEOAS links for related actions

Show child attributes

Getting Started

SMS API

USSD Webhooks

Payment API

Email API

Checkout API

Initiate Payment

Initiate Payment

Request Body

Responses

200 OK - Payment Initiated Successfully

400 Bad Request - Invalid Request Data

401 Unauthorized - Invalid Credentials

Response Fields

Authorizations

Body

Response

​Initiate Payment

​Request Body

​Responses

​200 OK - Payment Initiated Successfully

​400 Bad Request - Invalid Request Data

​401 Unauthorized - Invalid Credentials

​Response Fields

Authorizations

Body

Response

Initiate Payment

Request Body

Responses

200 OK - Payment Initiated Successfully

400 Bad Request - Invalid Request Data

401 Unauthorized - Invalid Credentials

Response Fields