​

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
  }'

​

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

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