Getting Started

Go from zero to your first authenticated collection request.

Step 1: Create an account

Sign in to the Korba Xchange dashboard to access your API credentials, transaction history, sandbox controls, and webhook configuration.

Go to the Korba Xchange dashboard

Step 2: Get your API credentials

Go to API / Website Creds in the dashboard. You will use these values to sign every API request.

Credential	Description
client_id	Your numeric client identifier. Include this in request bodies that require `client_id`.
client_key	Your public HMAC identifier. Include it in the authorization header as `Authorization: HMAC client_key:signature`.
secret_key	Your private signing key. Use it to generate the HMAC-SHA256 signature. Never expose it in browser code or version control.

Step 3: Set up your environment

All new accounts start in sandbox mode. Whitelist your server IP addresses and test phone numbers on the credentials page before sending requests.

Base URLs
Sandbox: https://testxchange.korba365.com/api/v1.0/
Live: https://xchange.korba365.com/api/v1.0/

Step 4: Make your first API call

The example below initiates a mobile money collection. Build the HMAC signature from the sorted request body fields, then send it in the Authorization header.

POST


    https://testxchange.korba365.com/api/v1.0/collect/

curl -X POST "https://testxchange.korba365.com/api/v1.0/collect/" \
  -H "Content-Type: application/json" \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -d '{
    "amount": "1.00",
    "callback_url": "https://yourapp.com/callbacks/collections/",
    "client_id": 2,
    "customer_number": "0241234567",
    "description": "Test collection",
    "network_code": "MTN",
    "transaction_id": "TXN-001"
  }'

# pip install requests
import hashlib, hmac, requests

CLIENT_KEY = "YOUR_CLIENT_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"

payload = {
    "amount": "1.00",
    "callback_url": "https://yourapp.com/callbacks/collections/",
    "client_id": 2,
    "customer_number": "0241234567",
    "description": "Test collection",
    "network_code": "MTN",
    "transaction_id": "TXN-001",
}

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/collect/",
    json=payload,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"HMAC {CLIENT_KEY}:{signature}",
    },
)
print(response.json())

200 OK

{
  "success": true,
  "results": "Transaction initiated successfully. Please Check Phone for prompt",
  "error_code": null
}

Step 5: Handle callbacks

Mobile money payments are asynchronous. The API response confirms that the request was accepted; final success or failure is delivered to your callback_url.

Korba Xchange calls your callback URL with the transaction result, including the original transaction_id, status, and message.

Read the Webhooks guide

Step 6: Go live

Test your integration end to end in sandbox.
Switch your dashboard account to production mode.
Whitelist your production server IP addresses.
Replace sandbox credentials with production credentials.
Update your base URL to https://xchange.korba365.com/api/v1.0/.

Previous Overview Next Authentication