curl --request GET \
--url https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status \
--header 'Authorization: Basic $(echo -n "username:password" | base64)'
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/20416369453214532143/status', {
method: 'GET',
headers: {
'Authorization': `Basic ${credentials}`
}
});
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.get(
'https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status',
headers={
'Authorization': f'Basic {credentials}'
}
)
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/20416369453214532143/status',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Basic ' . $credentials
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{
"statusCode": "0000",
"statusMessage": "Successful",
"transactionId": "20416369453214532143",
"data": {
"reference": "20416369453214532143",
"status": "COMPLETED",
"amount": 45,
"charge": 0.68,
"totalAmount": 45.68,
"payee": "Kairos",
"payer": "testOne",
"narration": "PIZZAMAN/CHICKMAN",
"msisdn": "233559400612",
"completedAt": "2024-07-17T14:30:00Z"
},
"links": [
{
"rel": "payment",
"href": "/v1/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
Get Transaction Status
Check the status of a payment transaction by reference
GET
/
v1
/
payment
/
{reference}
/
status
curl --request GET \
--url https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status \
--header 'Authorization: Basic $(echo -n "username:password" | base64)'
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/20416369453214532143/status', {
method: 'GET',
headers: {
'Authorization': `Basic ${credentials}`
}
});
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.get(
'https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status',
headers={
'Authorization': f'Basic {credentials}'
}
)
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/20416369453214532143/status',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Basic ' . $credentials
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{
"statusCode": "0000",
"statusMessage": "Successful",
"transactionId": "20416369453214532143",
"data": {
"reference": "20416369453214532143",
"status": "COMPLETED",
"amount": 45,
"charge": 0.68,
"totalAmount": 45.68,
"payee": "Kairos",
"payer": "testOne",
"narration": "PIZZAMAN/CHICKMAN",
"msisdn": "233559400612",
"completedAt": "2024-07-17T14:30:00Z"
},
"links": [
{
"rel": "payment",
"href": "/v1/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": {}
}Get Transaction Status
This endpoint allows you to check the current status of a payment transaction using its reference identifier. Endpoint:GET /v1/payment/{reference}/status
curl --request GET \
--url https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status \
--header 'Authorization: Basic $(echo -n "username:password" | base64)'
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/20416369453214532143/status', {
method: 'GET',
headers: {
'Authorization': `Basic ${credentials}`
}
});
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.get(
'https://api.staging.kairosafrika.cloud/paygw/v1/payment/20416369453214532143/status',
headers={
'Authorization': f'Basic {credentials}'
}
)
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/20416369453214532143/status',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Basic ' . $credentials
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
Path Parameter
- reference (string, required): The reference identifier of the payment transaction to check.
- Example:
20416369453214532143
- Example:
Responses
200 OK - Transaction Status Retrieved Successfully
{
"statusCode": "0000",
"statusMessage": "Successful",
"transactionId": "20416369453214532143",
"data": {
"reference": "20416369453214532143",
"status": "COMPLETED",
"amount": 45,
"charge": 0.68,
"totalAmount": 45.68,
"payee": "Kairos",
"payer": "testOne",
"narration": "PIZZAMAN/CHICKMAN",
"msisdn": "233559400612",
"completedAt": "2024-07-17T14:30:00Z"
},
"links": [
{
"rel": "payment",
"href": "/v1/payment"
}
]
}
404 Not Found - Transaction Not Found
{
"statusCode": "0404",
"statusMessage": "Transaction not found",
"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 request
"0000": Successful"0404": Transaction not found"0401": Unauthorized
- statusMessage (string): Human-readable status message
- transactionId (string): Unique transaction identifier for tracking
- data (object): Transaction details when successful
- reference (string): Reference identifier for the payment
- status (string): Current transaction status -
PENDING,COMPLETED,FAILED,CANCELLED - amount (number): Base payment amount
- charge (number): Processing charge amount
- totalAmount (number): Total amount including charges
- payee (string): Name of the payee receiving the payment
- payer (string): Name or identifier of the payer
- narration (string): Payment description or narration
- msisdn (string): Mobile subscriber identifier
- completedAt (string): ISO 8601 timestamp when transaction was completed (null if not completed)
- links (array): HATEOAS links for related actions
Transaction Status Values
- PENDING: Transaction is being processed
- COMPLETED: Transaction has been successfully completed
- FAILED: Transaction failed to process
- CANCELLED: Transaction was cancelled
Usage Example
Use this endpoint to check the current status of a payment transaction. This is particularly useful for:- Polling transaction status after initiating a payment
- Verifying payment completion before fulfilling orders
- Troubleshooting failed transactions
Authorizations
Basic authentication using base64 encoded username:password
Path Parameters
The reference identifier of the payment transaction
Response
Transaction status retrieved successfully
Status code indicating the result of the request
Example:
"0000"
Human-readable status message
Example:
"Successful"
Unique transaction identifier for tracking
Example:
"20416369453214532143"
Transaction details when successful
Show child attributes
Show child attributes
HATEOAS links for related actions
Show child attributes
Show child attributes