ā€‹
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).

ā€‹
Supported Transfer Types

OneKhusa categorizes single disbursements into three distinct transfer channels based on the target beneficiary destination:
Transfer TypeBeneficiary TargetDescriptionTypical Speed
Intra-OrganizationSub-merchant or merchant account within the same organizationFunds are transferred from one merchant account to another merchant account within the same organisation on OneKhusaInstant
Inter-OrganizationMerchant account belonging to a different OneKhusa organizationFunds are transferred from one merchant account to another merchant account registered on OneKhusa but belonging to a different organisationInstant
External TransferExternal Bank Account or Mobile Money WalletFunds are transferred from one merchant account to an external bank account or mobile wallet through the payment bridgeReal-time to Near Instant

ā€‹
How Disbursements Work (Execution Flow)

Core Event-Driven Flow
  1. Authentication: Obtain a bearer token via the POST /api-reference/get-started/getAccessToken endpoint.
  2. Initiate Transfer: Submit a payout payload specifying the source merchant account, amount, and beneficiary details matching the transfer route.
  3. 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.

ā€‹
Developer Best Practices & Operational Safeguards

  • 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.