Authentication

Korba Xchange uses HMAC-SHA256 to authenticate every API request. Each call must carry a cryptographic signature derived from your secret key and the request body — ensuring that requests cannot be tampered with in transit.

HMAC Authentication

HMAC (Hash-based Message Authentication Code) combines a secret key with a message and a hash function (SHA-256) to produce a fixed-length signature. Because the signature is derived from both the payload and your secret, any modification to the request body after signing will produce a different signature on the server — making it immediately detectable.

You will need two credentials, both available on your client dashboard under API/Website Creds:

• client_key — identifies your account in the Authorization header.
• secret_key — used to compute the HMAC signature. Never expose this publicly.

Generating the Signature

The HMAC signature is calculated from a message string built from your request body. Follow these steps exactly — the order matters:

1. Collect all key-value pairs from your request body.
2. Sort the keys in ascending (A → Z) alphabetical order.
3. Join them as key=value pairs separated by &.
4. Compute HMAC(secret_key, message, SHA-256).
5. Hex-encode the result to obtain the final signature string.

Message Construction Example

Given the following request body:

{
  "amount": "15.0",
  "callback_url": "https://www.myapp.com/callback",
  "client_id": 2,
  "customer_number": "0204000000",
  "network_code": "MTN",
  "transaction_id": "X4569"
}

After sorting keys alphabetically and joining as key=value&… pairs, the message string becomes:

amount=15.0&callback_url=https://www.myapp.com/callback&client_id=2&customer_number=0204000000&network_code=MTN&transaction_id=X4569

The HMAC signature formula (language-agnostic) is:

HMAC_signature = HMAC(secret_key, message, SHA256).hexEncode()

You can verify your implementation with the online HMAC generator — select SHA-256 as the algorithm.

Code Examples

The following snippets show how to build the message string and compute the HMAC signature in common languages.

import hmac, hashlib

secret_key = "YOUR_SECRET_KEY"
client_key = "YOUR_CLIENT_KEY"

# Request body params
params = {
    "amount": "15.0",
    "callback_url": "https://www.myapp.com/callback",
    "client_id": 2,
    "customer_number": "0204000000",
    "network_code": "MTN",
    "transaction_id": "X4569",
}

# 1. Sort keys ascending, build message string
message = "&".join(
    f"{k}={v}"
    for k, v in sorted(params.items())
)
# message → "amount=15.0&callback_url=https://www.myapp.com/callback&client_id=2&customer_number=0204000000&network_code=MTN&transaction_id=X4569"

# 2. Compute HMAC-SHA256 and hex-encode
signature = hmac.new(
    secret_key.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

# 3. Build Authorization header
auth_header = f"HMAC {client_key}:{signature}"

const crypto = require('crypto');

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

// Request body params
const params = {
  amount: '15.0',
  callback_url: 'https://www.myapp.com/callback',
  client_id: 2,
  customer_number: '0204000000',
  network_code: 'MTN',
  transaction_id: 'X4569',
};

// 1. Sort keys ascending, build message string
const message = Object.keys(params)
  .sort()
  .map(k => `${k}=${params[k]}`)
  .join('&');
// message → "amount=15.0&callback_url=https://www.myapp.com/callback&client_id=2&customer_number=0204000000&network_code=MTN&transaction_id=X4569"

// 2. Compute HMAC-SHA256 and hex-encode
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(message)
  .digest('hex');

// 3. Build Authorization header
const authHeader = `HMAC ${clientKey}:${signature}`;

# Compute HMAC signature with openssl (bash/zsh)

SECRET_KEY="YOUR_SECRET_KEY"
CLIENT_KEY="YOUR_CLIENT_KEY"

# 1. Build message string (keys already sorted ascending)
MESSAGE="amount=15.0&callback_url=https://www.myapp.com/callback&client_id=2&customer_number=0204000000&network_code=MTN&transaction_id=X4569"

# 2. Compute HMAC-SHA256 signature
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')

# 3. Send the authenticated request
curl -X POST \
  -H "Authorization: HMAC $CLIENT_KEY:$SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"amount":"15.0","callback_url":"https://www.myapp.com/callback","client_id":2,"customer_number":"0204000000","network_code":"MTN","transaction_id":"X4569"}' \
  https://xchange.korba365.com/api/v1.0/collect/

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

// Request body params
$params = [
    'amount'          => '15.0',
    'callback_url'    => 'https://www.myapp.com/callback',
    'client_id'       => 2,
    'customer_number' => '0204000000',
    'network_code'    => 'MTN',
    'transaction_id'  => 'X4569',
];

// 1. Sort keys ascending, build message string
ksort($params);
$parts = [];
foreach ($params as $k => $v) {
    $parts[] = "$k=$v";
}
$message = implode('&', $parts);
// $message → "amount=15.0&callback_url=https://www.myapp.com/callback&client_id=2&customer_number=0204000000&network_code=MTN&transaction_id=X4569"

// 2. Compute HMAC-SHA256 and hex-encode
$signature = hash_hmac('sha256', $message, $secretKey);

// 3. Build Authorization header
$authHeader = "HMAC $clientKey:$signature";

Authorization Header

Include the computed signature in every request using the Authorization header. The format is:

Authorization: HMAC {client_key}:{hmac_signature}

For example, if your client_key is BDAKEY1234 and the computed HMAC signature is bd93f30, a complete cURL request looks like:

curl -X POST \
  -H "Authorization: HMAC BDAKEY1234:bd93f30" \
  -H "Content-Type: application/json" \
  https://xchange.korba365.com/api/v1.0/collect/

Integration Modes

Korba Xchange provides two integration environments so you can develop and test safely before going live.

Sandbox Mode

All new accounts start in Sandbox mode by default. In sandbox mode, API calls are processed in a simulated environment — no real money moves and no real network transactions occur.

To begin testing you must whitelist the phone numbers or bank account numbers you intend to use. Navigate to Integration Mode on your client dashboard and add numbers under the Add Number tab. Requests using non-whitelisted numbers will be rejected in sandbox mode.

Production Mode

When you are ready to go live, request production access from your client dashboard by navigating to Integration Mode and selecting Request Production Access. Once approved, your account will be switched to production and real transactions will be processed.

IP Whitelisting

For security, Korba Xchange only accepts API requests from IP addresses that you have explicitly whitelisted. Any request originating from a non-whitelisted IP will be rejected, regardless of whether the HMAC signature is valid.

To manage your whitelisted IP addresses, log in to the client dashboard, navigate to API/Website Creds, and select the Whitelisted IP(S) tab. Add each server IP address from which your integration will make API calls.

Account Number Whitelisting

In Sandbox mode, API requests are also validated against a list of whitelisted account numbers. This applies to both mobile money phone numbers and bank account numbers. Requests using numbers that are not whitelisted will be rejected.

To whitelist account numbers, navigate to Integration Mode on the client dashboard and select the Add Number tab. You can add and manage numbers there at any time during development.