The Single Disbursements methods in the OneKhusa SDK allow a merchant to send funds from a merchant account to a beneficiary across three distinct transfer channels: Banks and Mobile Wallets (External Transfer), Intra-Organisation and Inter-Organisation. Every channel is exposed through client.Transactions.SingleDisbursements.

​
Key Business Use Cases

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

​
Supported Transfer Types

OneKhusa categorizes single disbursements into three distinct transfer channels based on the target beneficiary destination:
Transfer TypeBeneficiary TargetDescriptionTypical Speed
Banks and Mobile Wallets (External Transfer)External Bank Account or Mobile Money WalletFunds are transferred from a merchant account to an external bank account or mobile wallet through payment connectors (the payment bridge)Real-time to Near Instant
Intra-OrganisationSub-merchant or merchant account within the same organisationFunds are transferred from one merchant account to another merchant account within the same organisation entirely on the internal ledgerInstant
Inter-OrganisationMerchant account belonging to a different OneKhusa organisationFunds are transferred from one merchant account to another merchant account registered on OneKhusa but belonging to a different organisation, using the internal ledger with no external payment bridge involvementInstant

​
How Single Disbursements Work (Execution Flow)

Core Event-Driven Flow
  1. Configure the client: Instantiate OneKhusaClient with your API key, API secret, MerchantAccountNumber and OrganisationId.
  2. Initiate Transfer: Call the appropriate method (CreatePayoutAsync for external, CreateIntraTransferAsync for intra-organisation, CreateInterTransferAsync for inter-organisation) supplying the source merchant account, amount, and beneficiary details matching the transfer route.
  3. Processing & Status:
    • Intra- and Inter-Organisation transfers execute synchronously with immediate balance updates on the internal ledger.
    • External transfers to banks or mobile money networks process asynchronously via payment connectors, updating status asynchronously via webhooks.
  4. Approval Workflow: Depending on your organisation’s authorisation policy (2-eye, 4-eye or 6-eye), posted transfers are approved and, where required, reviewed before execution.

​
SDK Method and Namespace Reference

CategoryAdd / InitiateReviewApproveReject
Banks and Mobile WalletsCreatePayoutAsync (BankOrWallet)ReviewPayoutAsync (Shared)ApprovePayoutAsync (Shared)RejectPayoutAsync (Shared)
Intra-OrganisationCreateIntraTransferAsync (IntraOrganisation)ReviewIntraTransferAsync (Shared)ApproveIntraTransferAsync (Shared)RejectIntraTransferAsync (Shared)
Inter-OrganisationCreateInterTransferAsync (InterOrganisation)ReviewInterTransferAsync (Shared)ApproveInterTransferAsync (Shared)RejectInterTransferAsync (Shared)
Transaction inquiry is shared across all channels: use GetPayoutsAsync and GetPayoutAsync (Shared) to query posted payouts.

​
Developer Best Practices & Operational Safeguards

  • Idempotency Keys: Always supply a unique idempotency-key for disbursement requests to prevent duplicate payouts caused by transient network timeouts. The SDK generates one automatically if you do not provide it.
  • Account Balance Checks: Ensure the 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.