USSD OTP

Deliver one-time passcodes and custom messages to your users through USSD prompts or SMS. A single endpoint handles both channels — ideal for authentication flows, transaction confirmations, and secure verifications.

POST https://testxchange.korba365.com/api/v1.0/ussd_otp/

Overview

The USSD OTP endpoint triggers a USSD session or SMS delivery to the specified phone number. When a USSD session is active, the ussd_code is displayed as a prompt in the user's USSD menu. Optionally, an sms_message can be sent in parallel as a fallback for users who do not complete the USSD flow.

The platform parameter acts as an alias to help you identify which of your products or services triggered the OTP — useful for analytics and multi-product integrations.

USSD session validity. Each USSD session remains active for 5 minutes from the moment the OTP is created. After that window, the code expires and the user must request a new one. Design your UX to surface this timeout clearly — for example, show a countdown or a "Resend code" option at the 4-minute mark.

Request Body

Send a JSON body with the fields below. All MANDATORY fields must be present; omitting any will result in an error response.

Parameter	Type	Required	Description
client_id	string	Mandatory	Your unique client identifier, available from the dashboard under API/Website Creds.
phone_number	string	Mandatory	Recipient's phone number in international format. Must begin with the country code — e.g. `+233241234567`.
ussd_code	string	Mandatory	The code or message text to display to the user in the USSD session prompt.
sms_message	string	Optional	SMS content to deliver alongside the USSD prompt. Useful as a fallback for users who miss the USSD session.
platform	string	Optional	A short alphanumeric alias identifying the product or service initiating the OTP (e.g. `checkout`, `login`). Used for analytics and logs.

Request Example

The following examples show how to call the USSD OTP endpoint with both MANDATORY and optional parameters.

import hmac, hashlib, requests

secret_key = "YOUR_SECRET_KEY"
client_key = "YOUR_CLIENT_KEY"

payload = {
    "client_id":     "YOUR_CLIENT_ID",
    "phone_number":  "+233241234567",
    "ussd_code":     "Your OTP is 847291",
    "sms_message":   "Your Korba OTP is 847291. Valid for 5 minutes.",
    "platform":      "checkout",
}

message = "&".join(f"{k}={v}" for k, v in sorted(payload.items()))
signature = hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

response = requests.post(
    "https://testxchange.korba365.com/api/v1.0/ussd_otp/",
    json=payload,
    headers={"Authorization": f"HMAC {client_key}:{signature}"},
)
print(response.json())

const crypto = require('crypto');
const axios  = require('axios');

const secretKey = 'YOUR_SECRET_KEY';
const clientKey = 'YOUR_CLIENT_KEY';

const payload = {
  client_id:    'YOUR_CLIENT_ID',
  phone_number: '+233241234567',
  ussd_code:    'Your OTP is 847291',
  sms_message:  'Your Korba OTP is 847291. Valid for 5 minutes.',
  platform:     'checkout',
};

const message = Object.keys(payload).sort().map(k => `${k}=${payload[k]}`).join('&');
const signature = crypto.createHmac('sha256', secretKey).update(message).digest('hex');

axios.post('https://testxchange.korba365.com/api/v1.0/ussd_otp/', payload, {
  headers: { 'Authorization': `HMAC ${clientKey}:${signature}` },
}).then(r => console.log(r.data));

curl -X POST \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":    "YOUR_CLIENT_ID",
    "phone_number": "+233241234567",
    "ussd_code":    "Your OTP is 847291",
    "sms_message":  "Your Korba OTP is 847291. Valid for 5 minutes.",
    "platform":     "checkout"
  }' \
  https://testxchange.korba365.com/api/v1.0/ussd_otp/

<?php

$secretKey = 'YOUR_SECRET_KEY';
$clientKey = 'YOUR_CLIENT_KEY';

$payload = [
    'client_id'    => 'YOUR_CLIENT_ID',
    'phone_number' => '+233241234567',
    'ussd_code'    => 'Your OTP is 847291',
    'sms_message'  => 'Your Korba OTP is 847291. Valid for 5 minutes.',
    'platform'     => 'checkout',
];

ksort($payload);
$parts = [];
foreach ($payload as $k => $v) $parts[] = "$k=$v";
$message   = implode('&', $parts);
$signature = hash_hmac('sha256', $message, $secretKey);

$ch = curl_init('https://testxchange.korba365.com/api/v1.0/ussd_otp/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "Authorization: HMAC $clientKey:$signature",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

Response

A successful request returns HTTP 200 with the JSON body below. Any error is returned with an appropriate HTTP status code and an error_message field — see the Errors & Status Codes page for the full list.

200 OK Success

{
  "message":       "Code Created",
  "response_code": "00"
}

USSD short codes. To trigger a USSD OTP session the user must dial one of the following Korba short codes on their handset:

Live / Production: *365*0#
Test / Sandbox: *365*5#

Ensure your test flows use *365*5# to avoid sending live OTPs during development. Sessions expire after 5 minutes.

Previous MTN Direct Debit Next SMS