Korba Xchange / Docs

Airtime Topup

Transfer airtime to a recipient after funding the transaction from your Partner Wallet (OVA).

Collect before topup when charging an end customer. The old working docs state that a complete customer-paid topup flow first calls the Collections API to take money from the customer, then calls this Topup API to deliver airtime to the intended recipient.

Topup Endpoint

POST https://testxchange.korba365.com/api/v1.0/topup/
Parameter Type Required Description
customer_number string Mandatory Recipient phone number.
amount number Mandatory Amount of airtime to transfer.
transaction_id string Mandatory Unique ID generated by your system.
client_id integer Mandatory Your Client ID from the dashboard under API / Website Creds.
network_code string Mandatory Use a code returned by Topup Network Options. Common values are MTN, AIR, TIG, VOD, and GLO.
callback_url string Mandatory Callback URL called when the transaction completes. Final status is delivered as query parameters: transaction_id, status, and message.
description string Optional Description of your transaction.
payer_name string Optional Name of the payer for your records.
extra_info string Optional Additional metadata for your records.

Topup Network Options

Fetch the networks enabled for your account and use the returned code as network_code.

POST https://testxchange.korba365.com/api/v1.0/topup_network_options/
Example response
[
  {"name": "AirtelTigo", "code": "AIR"},
  {"name": "MTN", "code": "MTN"},
  {"name": "Telecel", "code": "VOD"},
  {"name": "GLO", "code": "GLO"}
]

Request Example

Topup request
curl -X POST https://testxchange.korba365.com/api/v1.0/topup/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_number": "024000000",
    "amount": 10.0,
    "transaction_id": "TOPUP-001",
    "client_id": 2,
    "network_code": "MTN",
    "callback_url": "https://www.myapp.com/callback",
    "description": "awesome description",
    "payer_name": "John Doe",
    "extra_info": "metadata"
  }'

Responses

200 OK
{
  "success": true,
  "results": "Transaction initiated successfully."
}
4xx Error
{
  "success": false,
  "error_code": 405,
  "error_message": "Invalid Network Code"
}

Error Codes

CodeDescription
400Missing or invalid customer number.
401Missing or invalid transaction ID.
402Missing or invalid amount.
403Missing wallet/network code.
404Missing or invalid callback URL.
405Invalid network code.
407Duplicate transaction ID.
408Invalid callback URL.
409Invalid amount.
410Invalid customer number format.
Previous Disbursements Next Data Bundles