Overview

Key Business Use Cases

Internal Payouts: Real-time account balance reallocation between internal departments or sub-merchants.
B2B Transfers: Direct merchant-to-merchant payouts across different organizations operating on OneKhusa.
External Payouts: Automated payout processing to customer bank accounts or mobile money wallets (e.g., payroll, vendor payments, platform withdrawals).

OneKhusa categorizes single disbursements into three distinct transfer channels based on the target beneficiary destination:

Transfer Type	Beneficiary Target	Description	Typical Speed
Intra-Organization	Sub-merchant or merchant account within the same organization	Funds are transferred from one merchant account to another merchant account within the same organisation on OneKhusa	Instant
Inter-Organization	Merchant account belonging to a different OneKhusa organization	Funds are transferred from one merchant account to another merchant account registered on OneKhusa but belonging to a different organisation	Instant
External Transfer	External Bank Account or Mobile Money Wallet	Funds are transferred from one merchant account to an external bank account or mobile wallet through the payment bridge	Real-time to Near Instant

Authentication: Obtain a bearer token via the POST /api-reference/get-started/getAccessToken endpoint.
Initiate Transfer: Submit a payout payload specifying the source merchant account, amount, and beneficiary details matching the transfer route.
Processing & Status:
- Internal transfers execute synchronously with immediate balance updates.
- External transfers to banks or mobile money networks process asynchronously via the payment bridge, updating status asynchronously via webhooks.

Idempotency Keys: Always supply a unique idempotency-key in your request headers for disbursement requests to prevent duplicate payouts caused by transient network timeouts.
Account Balance Checks: Ensure your merchant account maintains sufficient cleared (available) funds prior to initiating disbursements; overdraft transfers will be rejected automatically (400 Insufficient funds).
Webhook Handling: Implement webhook listeners to receive final execution states (SUCCESS, FAILED, REVERSED) for external payouts.