Collections

Accept and receive money from customers directly into your Partner Wallet (OVA) using mobile money networks and card payments.

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

Always rely on the callback for final status. The synchronous response confirms the transaction has been initiated — not completed. Do not fulfill orders or credit accounts based on the initial response alone. Use the callback_url to receive the definitive SUCCESS or FAILED outcome.

Card transactions require a redirect_url. When network_code is CRD, the customer is redirected to a hosted card payment page. Set redirect_url to the URL you want them returned to after payment. A description is also required for card transactions.

Overview

The Collections endpoint lets you initiate a debit request against a customer's mobile money wallet or card. Once submitted, the customer receives a payment prompt on their phone (for mobile money) or is redirected to the card payment page. The collected funds are credited to your Korba Xchange OVA (Partner Wallet).

Each collection request must carry a unique transaction_id from your system. Duplicate IDs are rejected with error code 407. Use the network options endpoint to discover which payment channels are enabled for your account before building your checkout UI.

Request Body

Send a JSON body with Content-Type: application/json.

Parameter	Type	Required	Description
customer_number	string	Yes*	Customer's mobile number. Optional for card (`CRD`) transactions.
amount	number	Yes	Amount to debit from the customer. Must be a positive number.
transaction_id	string	Yes	A unique identifier from your system for this transaction. Duplicate IDs are rejected.
client_id	integer	Yes	Your Client ID found in the dashboard under API / Website Credentials.
network_code	string	Yes	Payment channel code. Obtain available codes from the Network Options endpoint (e.g. `MTN`, `AIR`, `CRD`).
callback_url	string	Yes	A publicly accessible URL on your server. Called when the transaction completes with the final status.
description	string	Optional*	A short description of the payment. Required when `network_code` is `CRD`.
redirect_url	string	Optional*	URL to redirect the customer after card payment. Required when `network_code` is `CRD`.
payer_name	string	Optional	Name of the customer making the payment.
extra_info	string	Optional	Any additional metadata or reference information you wish to attach to the transaction.

Network Options

Before initiating a collection you should fetch the list of payment networks enabled for your account. This allows you to populate a payment method selector in your UI dynamically.

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

Send your client_id in the JSON body. The response is a list of available network objects:

Field	Type	Description
id	integer	Internal network identifier.
name	string	Human-readable network name (e.g. "MTN Mobile Money").
code	string	The code to pass as `network_code` in your collection request. Common codes: `MTN`, `AIR`, `TIG`, `VOD`, `CRD`.

Request Example

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": 10.0,
    "callback_url": "https://www.myapp.com/callback",
    "client_id": 2,
    "customer_number": "024000000",
    "description": "Payment for order #1234",
    "network_code": "MTN",
    "transaction_id": "X13454"
  }'

import hmac, hashlib, requests

secret_key = "YOUR_SECRET_KEY"
client_key = "YOUR_CLIENT_KEY"

payload = {
    "amount":          10.0,
    "callback_url":   "https://www.myapp.com/callback",
    "client_id":      2,
    "customer_number": "024000000",
    "description":   "Payment for order #1234",
    "network_code":  "MTN",
    "transaction_id": "X13454",
}

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={"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 = {
  amount:          10.0,
  callback_url:   'https://www.myapp.com/callback',
  client_id:      2,
  customer_number: '024000000',
  description:    'Payment for order #1234',
  network_code:   'MTN',
  transaction_id: 'X13454',
};

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/collect/', payload, {
  headers: { 'Authorization': `HMAC ${clientKey}:${signature}` },
}).then(r => console.log(r.data));

<?php

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

$payload = [
    'amount'          => 10.0,
    'callback_url'   => 'https://www.myapp.com/callback',
    'client_id'      => 2,
    'customer_number' => '024000000',
    'description'    => 'Payment for order #1234',
    'network_code'   => 'MTN',
    'transaction_id' => 'X13454',
];

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/collect/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "Authorization: HMAC {$clientKey}:{$signature}",
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($response, true));

Success Response

A 200 OK with success: true means the transaction was accepted and initiated. The customer will receive a prompt on their mobile device.

200 OK

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

For card (CRD) transactions, redirect_url will contain the hosted payment page URL where you should redirect the customer.

Error Response

On failure, success is false and the body includes an error_code and a human-readable error_message.

4xx Error

{
  "success": false,
  "error_code": 405,
  "error_message": "Invalid network code"
}

Error Codes

Common collection errors fall within the 400-411 range.

Code	Description
400	Missing or invalid customer number.
402	Missing or invalid `amount`.
403	Invalid wallet code or wallet not configured.
404	Missing or invalid `callback_url`.
405	Invalid `network_code`. Use the network options endpoint to get valid codes.
407	Duplicate `transaction_id`. This ID has already been processed.
408	Invalid `callback_url` format. Must be a valid, publicly accessible HTTP/HTTPS URL.
409	Invalid amount format. Amount must be a positive number.
410	Invalid customer number format. Ensure the number is in the correct local format.
411	Missing `transaction_id`.

Callback Parameters

When a transaction reaches a terminal state, Korba Xchange sends an HTTP GET request to your callback_url with the result appended as query parameters. Your endpoint must return a 2xx response to acknowledge receipt.

Parameter	Type	Description
transaction_id	string	The unique ID you provided when initiating the transaction.
status	string	`SUCCESS` — payment was received. `FAILED` — payment was not completed.
message	string	A human-readable description of the outcome.

Example Callback Payload

{
  "transaction_id": "X13454",
  "status": "SUCCESS",
  "message": "Transaction completed successfully"
}

{
  "transaction_id": "X13454",
  "status": "FAILED",
  "message": "Customer cancelled the payment request"
}

Direct Card Collection

Direct card collection lets enabled clients initiate a card debit by submitting card details directly to the API. A successful request returns a redirect_url that the customer must follow to complete 3D Secure authentication when required.

The success redirect is not final status. Treat the redirect as part of the card authentication flow. Confirm final status through the callback or transaction status endpoint before fulfilling an order.

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

Parameter	Required	Description
client_id	Mandatory	Your Client ID from the dashboard.
card_number	Mandatory	Customer card number.
cvv	Mandatory	Card security code.
card_name	Mandatory	Name printed on the card.
expiry_month, expiry_year	Mandatory	Card expiry month and year.
amount	Mandatory	Amount to debit.
transaction_id	Mandatory	Unique transaction reference from your system.
callback_url	Mandatory	URL that receives the final card debit result.
success_redirect_url	Optional	URL to redirect the customer to after a successful card authentication flow.
failure_redirect_url	Optional	URL to redirect the customer to after a failed card authentication flow.
description	Optional	Transaction description. Defaults to `Card Direct`.

Direct Card Request

{
  "client_id": 2,
  "card_number": "4042123456789012",
  "cvv": "808",
  "card_name": "THOMAS CLEGG",
  "amount": "1.00",
  "expiry_month": "07",
  "expiry_year": "29",
  "transaction_id": "CARD-20260626-001",
  "callback_url": "https://yourapp.com/callbacks/card/",
  "description": "Order ID - 4045",
  "success_redirect_url": "https://yourapp.com/card-success/",
  "failure_redirect_url": "https://yourapp.com/card-failed/"
}

200 OK

{
  "success": true,
  "results": "Transaction initiated successfully, follow the link to complete the transaction",
  "redirect_url": "https://testxchange.korba365.com/threeds/?token=f7b272f"
}

Exchange Rate

Fetch the current exchange rate applicable to your collection transactions. Useful for displaying conversion rates to customers or for reconciliation when dealing with multi-currency scenarios.

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

curl -X POST https://testxchange.korba365.com/api/v1.0/get_exchange_rate/ \
  -H "Content-Type: application/json" \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -d '{
    "client_id": 2
  }'

import hmac, hashlib, requests

secret_key = "YOUR_SECRET_KEY"
client_key = "YOUR_CLIENT_KEY"

payload = {
    "client_id": 2,
}

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/get_exchange_rate/",
    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: 2,
};

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/get_exchange_rate/', payload, {
  headers: { 'Authorization': `HMAC ${clientKey}:${signature}` },
}).then(r => console.log(r.data));

<?php

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

$payload = [
    'client_id' => 2,
];

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/get_exchange_rate/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "Authorization: HMAC {$clientKey}:{$signature}",
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($response, true));

Previous Authentication Next XCheckout