curl --request POST \
  --url https://api.kairosafrika.com/v1/external/generate/otp \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'x-api-version: 2025-08-01' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": "0559400612",
    "from": "PHCCU",
    "message": "Your verification code is {code}, it expires in {amount} {duration}",
    "pinLength": 4,
    "pinType": "NUMERIC",
    "expiry": {
      "amount": 12,
      "duration": "minutes"
    },
    "maxAmountOfValidationRetries": 3
  }'

const response = await fetch('https://api.kairosafrika.com/v1/external/generate/otp', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'x-api-secret': 'YOUR_API_SECRET',
    'x-api-version': '2025-08-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: '0559400612',
    from: 'PHCCU',
    message: 'Your verification code is {code}, it expires in {amount} {duration}',
    pinLength: 4,
    pinType: 'NUMERIC',
    expiry: {
      amount: 12,
      duration: 'minutes'
    },
    maxAmountOfValidationRetries: 3
  })
});

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

import requests

response = requests.post(
    'https://api.kairosafrika.com/v1/external/generate/otp',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'x-api-secret': 'YOUR_API_SECRET',
        'x-api-version': '2025-08-01',
        'Content-Type': 'application/json'
    },
    json={
        'recipient': '0559400612',
        'from': 'PHCCU',
        'message': 'Your verification code is {code}, it expires in {amount} {duration}',
        'pinLength': 4,
        'pinType': 'NUMERIC',
        'expiry': {
            'amount': 12,
            'duration': 'minutes'
        },
        'maxAmountOfValidationRetries': 3
    }
)

result = response.json()
print(result)

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/generate/otp',
  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(
    'recipient' => '0559400612',
    'from' => 'PHCCU',
    'message' => 'Your verification code is {code}, it expires in {amount} {duration}',
    'pinLength' => 4,
    'pinType' => 'NUMERIC',
    'expiry' => array(
      'amount' => 12,
      'duration' => 'minutes'
    ),
    'maxAmountOfValidationRetries' => 3
  )),
  CURLOPT_HTTPHEADER => array(
    'x-api-key: YOUR_API_KEY',
    'x-api-secret: YOUR_API_SECRET',
    'x-api-version: 2025-08-01',
    'Content-Type: application/json'
  ),
));

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

{
  "statusCode": "200",
  "statusMessage": "OTP successfully sent to your device",
  "transactionId": "ec1fb725-3e86-47dc-bf0c-82b7776080e8",
  "sequenceNo": "01K6NA4F7KJKSR6JM912JMY4NV",
  "data": {
    "uuid": "b6ec4e28-c496-4ea5-b6e6-6a31301f3a79",
    "code": "***********"
  },
  "timestamp": "2025-10-03T15:13:03.227Z"
}

{
  "error": "INVALID_PHONE_NUMBER",
  "message": "The provided phone number is not valid",
  "details": {}
}

{
  "error": "INVALID_PHONE_NUMBER",
  "message": "The provided phone number is not valid",
  "details": {}
}

POST

external

generate

otp

curl --request POST \
  --url https://api.kairosafrika.com/v1/external/generate/otp \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'x-api-version: 2025-08-01' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": "0559400612",
    "from": "PHCCU",
    "message": "Your verification code is {code}, it expires in {amount} {duration}",
    "pinLength": 4,
    "pinType": "NUMERIC",
    "expiry": {
      "amount": 12,
      "duration": "minutes"
    },
    "maxAmountOfValidationRetries": 3
  }'

const response = await fetch('https://api.kairosafrika.com/v1/external/generate/otp', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'x-api-secret': 'YOUR_API_SECRET',
    'x-api-version': '2025-08-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: '0559400612',
    from: 'PHCCU',
    message: 'Your verification code is {code}, it expires in {amount} {duration}',
    pinLength: 4,
    pinType: 'NUMERIC',
    expiry: {
      amount: 12,
      duration: 'minutes'
    },
    maxAmountOfValidationRetries: 3
  })
});

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

import requests

response = requests.post(
    'https://api.kairosafrika.com/v1/external/generate/otp',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'x-api-secret': 'YOUR_API_SECRET',
        'x-api-version': '2025-08-01',
        'Content-Type': 'application/json'
    },
    json={
        'recipient': '0559400612',
        'from': 'PHCCU',
        'message': 'Your verification code is {code}, it expires in {amount} {duration}',
        'pinLength': 4,
        'pinType': 'NUMERIC',
        'expiry': {
            'amount': 12,
            'duration': 'minutes'
        },
        'maxAmountOfValidationRetries': 3
    }
)

result = response.json()
print(result)

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/generate/otp',
  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(
    'recipient' => '0559400612',
    'from' => 'PHCCU',
    'message' => 'Your verification code is {code}, it expires in {amount} {duration}',
    'pinLength' => 4,
    'pinType' => 'NUMERIC',
    'expiry' => array(
      'amount' => 12,
      'duration' => 'minutes'
    ),
    'maxAmountOfValidationRetries' => 3
  )),
  CURLOPT_HTTPHEADER => array(
    'x-api-key: YOUR_API_KEY',
    'x-api-secret: YOUR_API_SECRET',
    'x-api-version: 2025-08-01',
    'Content-Type: application/json'
  ),
));

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

{
  "statusCode": "200",
  "statusMessage": "OTP successfully sent to your device",
  "transactionId": "ec1fb725-3e86-47dc-bf0c-82b7776080e8",
  "sequenceNo": "01K6NA4F7KJKSR6JM912JMY4NV",
  "data": {
    "uuid": "b6ec4e28-c496-4ea5-b6e6-6a31301f3a79",
    "code": "***********"
  },
  "timestamp": "2025-10-03T15:13:03.227Z"
}

{
  "error": "INVALID_PHONE_NUMBER",
  "message": "The provided phone number is not valid",
  "details": {}
}

{
  "error": "INVALID_PHONE_NUMBER",
  "message": "The provided phone number is not valid",
  "details": {}
}

Generate OTP

This endpoint allows you to generate and send a one-time password (OTP) to a recipient via SMS. The OTP can be used for verification purposes with customizable expiry time and retry limits. Endpoint: POST /v1/external/generate/otp

curl --request POST \
  --url https://api.kairosafrika.com/v1/external/generate/otp \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'x-api-version: 2025-08-01' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": "0559400612",
    "from": "PHCCU",
    "message": "Your verification code is {code}, it expires in {amount} {duration}",
    "pinLength": 4,
    "pinType": "NUMERIC",
    "expiry": {
      "amount": 12,
      "duration": "minutes"
    },
    "maxAmountOfValidationRetries": 3
  }'

const response = await fetch('https://api.kairosafrika.com/v1/external/generate/otp', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'x-api-secret': 'YOUR_API_SECRET',
    'x-api-version': '2025-08-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: '0559400612',
    from: 'PHCCU',
    message: 'Your verification code is {code}, it expires in {amount} {duration}',
    pinLength: 4,
    pinType: 'NUMERIC',
    expiry: {
      amount: 12,
      duration: 'minutes'
    },
    maxAmountOfValidationRetries: 3
  })
});

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

import requests

response = requests.post(
    'https://api.kairosafrika.com/v1/external/generate/otp',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'x-api-secret': 'YOUR_API_SECRET',
        'x-api-version': '2025-08-01',
        'Content-Type': 'application/json'
    },
    json={
        'recipient': '0559400612',
        'from': 'PHCCU',
        'message': 'Your verification code is {code}, it expires in {amount} {duration}',
        'pinLength': 4,
        'pinType': 'NUMERIC',
        'expiry': {
            'amount': 12,
            'duration': 'minutes'
        },
        'maxAmountOfValidationRetries': 3
    }
)

result = response.json()
print(result)

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/generate/otp',
  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(
    'recipient' => '0559400612',
    'from' => 'PHCCU',
    'message' => 'Your verification code is {code}, it expires in {amount} {duration}',
    'pinLength' => 4,
    'pinType' => 'NUMERIC',
    'expiry' => array(
      'amount' => 12,
      'duration' => 'minutes'
    ),
    'maxAmountOfValidationRetries' => 3
  )),
  CURLOPT_HTTPHEADER => array(
    'x-api-key: YOUR_API_KEY',
    'x-api-secret: YOUR_API_SECRET',
    'x-api-version: 2025-08-01',
    'Content-Type: application/json'
  ),
));

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

Request Body

recipient (string, required): Recipient phone number (without + prefix).
from (string, required): Sender ID or name.
message (string, required): OTP message template with placeholders:
- {code} - Will be replaced with the generated OTP code
- {amount} - Will be replaced with expiry amount
- {duration} - Will be replaced with expiry duration
pinLength (integer, required): Length of the OTP code (4-10 digits).
pinType (string, required): Type of OTP code (NUMERIC, ALPHANUMERIC, or ALPHABETIC).
expiry (object, required): OTP expiry configuration.
- amount (integer, required): Expiry time amount.
- duration (string, required): Expiry time duration unit (seconds, minutes, or hours).
maxAmountOfValidationRetries (integer, required): Maximum number of validation attempts allowed (minimum 1).

Responses

200 OK: OTP generated and sent successfully.
400 Bad Request: Invalid input data.
401 Unauthorized: Invalid or missing API key.

Response Example

{
  "statusCode": "200",
  "statusMessage": "OTP successfully sent to your device",
  "transactionId": "ec1fb725-3e86-47dc-bf0c-82b7776080e8",
  "sequenceNo": "01K6NA4F7KJKSR6JM912JMY4NV",
  "data": {
    "uuid": "b6ec4e28-c496-4ea5-b6e6-6a31301f3a79",
    "code": "***********"
  },
  "timestamp": "2025-10-03T15:13:03.227Z"
}

Response Fields

statusCode (string): HTTP status code.
statusMessage (string): Status message (e.g., “OTP successfully sent to your device”).
transactionId (string): Unique transaction identifier.
sequenceNo (string): Sequence number for tracking.
data (object): OTP generation result data.
- uuid (string): Unique identifier for the OTP generation.
- code (string): Masked OTP code for security.
timestamp (string): ISO 8601 timestamp of the response.

Usage Flow

Generate OTP: Call this endpoint to generate and send an OTP to the recipient.
Validate OTP: Use the Validate OTP endpoint to verify the code entered by the user.
The OTP will expire after the specified time period.
Users have a limited number of validation attempts (as specified in maxAmountOfValidationRetries).

Authorizations

x-api-key

string

header

required

API Key for authentication

x-api-secret

string

header

required

API Secret for authentication

Headers

x-api-version

enum<string>

required

API version header (required for full JSON response)

Available options:

2025-08-01

Body

application/json

recipient

string

required

Recipient phone number (without + prefix)

Example:

"0559400612"

from

string

required

Sender ID or name

Example:

"PHCCU"

message

string

required

OTP message template with {code}, {amount}, and {duration} placeholders

Example:

"Your verification code is {code}, it expires in {amount} {duration}"

pinLength

integer

required

Length of the OTP code

Required range: 4 <= x <= 10

Example:

4

pinType

enum<string>

required

Type of OTP code

Available options:

NUMERIC,

ALPHANUMERIC,

ALPHABETIC

Example:

"NUMERIC"

expiry

object

required

Show child attributes

maxAmountOfValidationRetries

integer

required

Maximum number of validation attempts allowed

Required range: x >= 1

Example:

3

Response

OTP generated and sent successfully

statusCode

string

HTTP status code

Example:

"200"

statusMessage

string

Status message

Example:

"OTP successfully sent to your device"

transactionId

string

Unique transaction identifier

Example:

"ec1fb725-3e86-47dc-bf0c-82b7776080e8"

sequenceNo

string

Sequence number

Example:

"01K6NA4F7KJKSR6JM912JMY4NV"

data

object

Show child attributes

timestamp

string<date-time>

ISO 8601 timestamp

Example:

"2025-10-03T15:13:03.227Z"

Getting Started

SMS API

USSD Webhooks

Payment API

Email API

Checkout API

Generate OTP

Generate OTP

Request Body

Responses

Response Example

Response Fields

Usage Flow

Authorizations

Headers

Body

Response

​Generate OTP

​Request Body

​Responses

​Response Example

​Response Fields

​Usage Flow

Authorizations

Headers

Body

Response

Generate OTP

Request Body

Responses

Response Example

Response Fields

Usage Flow