Disbursements

Send money from your Partner Wallet (OVA) to mobile money wallets or bank accounts. Use /disburse/ for standard payouts and /remittance/ when you need to include remittance sender details.

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

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

OVA balance is debited for payouts. Check your available balance before sending large or batch disbursements.

Request Body

Send JSON with Content-Type: application/json and the HMAC authorization header. Mobile money disbursements use network_code values such as MTN, AIR, TIG, and VOD. Bank transfers use ISP.

Parameter	Required	Description
customer_number	Mandatory for mobile money	Recipient mobile number in local format, for example `0241234567`. Not required when `network_code` is `ISP`.
amount	Mandatory	Amount to pay out.
transaction_id	Mandatory	Unique reference from your system.
client_id	Mandatory	Your Client ID from the dashboard.
network_code	Mandatory	Destination channel code. Use `ISP` for bank transfers.
callback_url	Mandatory	Public URL that receives the final transaction outcome.
description	Optional	Transaction narration. Required for some bank transfer rails.
payer_name, payer_mobile	Optional	Sender name and sender mobile number. Recommended for bank and remittance requests.
extra_info	Optional	Additional metadata for reconciliation.

Bank Transfer Fields

When network_code is ISP, include the bank fields below.

Parameter	Required	Description
bank_account_number	Mandatory	Recipient bank account number.
bank_account_name	Mandatory	Verified recipient account name from customer lookup.
bank_code	Mandatory	Bank code from the authorized bank list.
recipient_bank_name	Recommended	Bank name from the authorized bank list.

Remittance Fields

The /remittance/ endpoint accepts the same payout fields plus remittance metadata. These fields can also be supplied on /disburse/ when you need the information stored for reporting.

Parameter	Required	Description
sender_amount	Optional	Amount debited from the sender.
sender_currency	Optional	Currency debited from the sender, for example `USD`.
sender_country	Optional	Originating country in ISO 3166-1 alpha-3 format, for example `USA`.
beneficiary_name	Optional	Recipient or beneficiary name. If omitted, the API falls back to `sender_name` where provided.

Examples

Mobile Money Disbursement

Request

curl -X POST https://testxchange.korba365.com/api/v1.0/disburse/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 2,
    "customer_number": "0241234567",
    "amount": "100.00",
    "transaction_id": "DIS-20260626-001",
    "network_code": "MTN",
    "callback_url": "https://yourapp.com/callbacks/disburse/",
    "description": "Staff salary payment",
    "payer_name": "Acme Ltd",
    "sender_amount": "100.00",
    "sender_currency": "GHS",
    "sender_country": "GHA",
    "beneficiary_name": "Yaw Sarpong"
  }'

Bank Transfer

Request

curl -X POST https://testxchange.korba365.com/api/v1.0/disburse/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 2,
    "amount": "500.00",
    "transaction_id": "DIS-BANK-20260626-001",
    "network_code": "ISP",
    "callback_url": "https://yourapp.com/callbacks/disburse/",
    "description": "Vendor payment",
    "bank_account_number": "1001000425098",
    "bank_account_name": "Jane Doe",
    "recipient_bank_name": "ECOBANK GHANA LTD",
    "bank_code": "300312",
    "payer_name": "John Doe",
    "payer_mobile": "0244123456",
    "sender_amount": "40.00",
    "sender_currency": "USD",
    "sender_country": "USA"
  }'

Lookup Endpoints

Disbursement Network Options

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

Authorized Bank List

Use this endpoint to fetch active banks and the bank codes required for ISP transfers.

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

200 OK

{
  "results": [
    {
      "bank_code": "300312",
      "full_name": "ECOBANK GHANA LTD"
    }
  ],
  "response_code": "100"
}

Authorized Customer Lookup

Verify the account name before sending a bank or momo transfer.

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

Bank Account Customer Lookup Request

{
  "client_id": 2,
  "bank_account_number": "1001000425098",
  "bank_code": "300312"
}

Responses

200 OK

{
  "success": true,
  "data": {
        "StatusCode":"100",
        "StatusMessage":"Success",
        "AccountName":"THOMAS AKOLOVI",
        "AccountNumber":"20********8",
        "BankCode":"300323",
        "BankName":"FIDELITY BANK LIMITED"
    },
  "error_code": null
}

400 Bad Request

{
  "success": false,
  "error_code": 407,
  "error_message": "Duplicate Transaction ID"
}

Callbacks

The synchronous response only confirms that the payout was accepted for processing. Korba Xchange calls your callback_url with the final transaction_id, status, and message.

Callback Example

https://yourapp.com/callbacks/disburse/?transaction_id=DIS-20260626-001&status=SUCCESS&message=Transaction%20completed

Previous WooCommerce Next Airtime Topup