When building corporate payout (disbursement) pipelines, whether you are pushing single payroll items or dispatching large file-based batches - ensuring operational guardrails is essential. To protect your corporate liquidity from unintended transfers or internal fraud, OneKhusa enforces a flexible, role-based workflow system called Authorisation Levels. Depending on your organization’s compliance policy, a disbursement transaction can require 1, 2, or 3 distinct human/system checkpoints before a single penny moves from your merchant account to bank account or mobile wallet.

​
1. What are Authorisation Levels?

Authorisation levels define the precise workflow pipeline required to transitions a disbursement transaction out of a staged state into actual funds transfer settlement. Based on your merchant settings, your account operates under one of three tiers:

​
Tier 1: Initiator Only (levelNumber: 1)

  • Workflow: Initiator Only
  • Mechanics: Immediate execution. As soon as your API client pushes a well-formed single or batch disbursement, it passes directly to the carrier or clearing network without human intervention. Ideal for agile environments or automated low-value micro-payouts.

​
Tier 2: Initiator -> Approver (levelNumber: 2)

  • Workflow: Initiator -> Approver
  • Mechanics: Double-entry guardrail. The API client initiates the transaction. The transaction status transitions to a staged approval state. Funds only are credited to the beneficiary after an Approver manually authorizes it.

​
Tier 3: Initiator -> Reviewer -> Approver (levelNumber: 3)

  • Workflow: Initiator -> Reviewer -> Approver
  • Mechanics: Institutional three-step compliance flow.
    1. The API triggers the payment.
    2. A Reviewer must inspect the transactions and mark them as verified (moving the transaction from state code P100 - Pending to R100 - Reviewed).
    3. An Approver performs the final authorization to trigger the actual transferring of funds to the beneficiary (S100 - Successful).

​
2. Single vs. Batch Disbursements

No matter which authorisation tier your company utilizes, the workflow steps apply evenly across both single and batch transactions.

​
Single Disbursements

Single disbursements route an immediate payment to one target bank account or mobile money wallet.
  • If Tier 1: The endpoint returns immediate execution confirmation, and your webhooks follow the transaction state to success.
  • If Tier 2 or 3: The API call will respond with a successful queuing transaction, but the payment will sit securely in a pending state until authorized by the approver.

​
Batch Disbursements

Batch disbursements allow your application to aggregate hundreds of payouts into a unified array collection (e.g., corporate payroll distribution or vendor settlement lists).
  • Operational Behavior: The entire collection inherits the security level configuration. If your company operates on Tier 2 (Initiator -> Approver), your system can programmatically push a 500-recipient batch payload via the API, but the execution matrix remains paused until a manager approves the batch. This eliminates the risk of an automated system bug accidentally distributing funds unchecked.

​
3. Developer Integration Guidelines

To build a flawless payout system around these institutional guardrails, integrate the following design patterns:
  1. Do Not Assume Instant Payouts: If your client account uses Tier 2 or Tier 3 workflows, your application logic must not assume that a successful 200/202 response from our API means the money has reached the user. Your user interface should clearly state: ” Payout staged for corporate review.”
  2. Rely on Webhook State Events: When an approver executes “Approve” action hours after your API request was sent, our gateway instantly triggers a webhook callback to your server. Your system should listen for final state transitions (SUCCESS alongside S100 response codes) to update your internal account/ledgers automatically.
  3. Proactively Query Configuration State: If you write cross-tenant enterprise software, query the /merchants/accounts/get endpoint during the initialization phase of your platform. This allows your application to dynamically show or hide approval-tracking workflows directly inside your own UI based on your customer’s underlying security configurations.