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": {}
}Endpoints
Initiate Payment
Initiate a new payment transaction
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;
?>
{
"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
Basic authentication using base64 encoded username:password
Body
application/json
Payment amount
Example:
1
Reference number for the payment
Example:
"889909909229"
Name of the payee receiving the payment
Example:
"Kairos"
Payment description or narration
Example:
"PIZZAMAN/CHICKMAN"
Msisdn identifier for the payment
Example:
"233559400612"
Callback identifier for payment status updates
Example:
"6607c05155dfd4919c18c44"
Name or identifier of the payer
Example:
"testOne"
Response
Payment initiated successfully
Status code indicating the result of the payment initiation
Example:
"0001"
Human-readable status message
Example:
"PENDING"
Unique transaction identifier for tracking
Example:
"20416369453214532143"
Payment details when successful
Show child attributes
Show child attributes
HATEOAS links for related actions
Show child attributes
Show child attributes