19 August 2026 - OneKhusa Payment Gateway

New Section: Getting Started

Moved Getting Started from API Reference to Getting Started.
Moved Terminology from API Reference to Getting Started.
Moved Rate Limiting from API Reference to Getting Started.
Moved Idempotency from API Reference to Getting Started.
Moved Error Handling from API Reference to Getting Started.
Moved Quick Integration from API Reference to Getting Started.
Moved Disclaimer from API Reference to Getting Started.
Added Settlement of Funds guide documenting settlement timelines (T+0, T+1, T+2), balance lifecycle, and settlement cycle matrix for different payment methods.
Added Transaction Fee Rules guide explaining fee deduction rules (Charge to Customer vs. Charge to Merchant) and the transaction type integration matrix.
Added Disbursement Authorisation Levels guide covering Tier 1 (Initiator Only), Tier 2 (Initiator + Approver), and Tier 3 (Initiator + Reviewer + Approver) workflows.
Added Transaction Statuses and Responses guide explaining the dual-layer transaction tracking system (Response Codes for root-cause analysis and Transaction Statuses for lifecycle state).
Added Mastering Webhooks guide covering webhook fundamentals, why polling is dangerous, retry configurations, step-by-step execution lifecycle, and best practices for production integrations.

API updates

This section highlights the new releases and improvements for OneKhusa API.

Bill Payments

Added Bill Payments Overview documenting the bill payment workflow and service provider integration.
Added Service Providers page listing available bill payment service providers and their service codes.
Added Test Accounts for sandbox testing of bill payment transactions.
Added Bill Payments API endpoint for processing bill payment transactions.

Merchants

Create Merchant

Request Body — The request now includes additional fields:

curl -X POST "https://api.onekhusa.com/sandbox/v1/merchants/accounts/add" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  -d '{
    "accountName": "AVIATION",
    "currencyCode": "MWK",
    "categoryCode": "8352",                                     // NEW
    "postalAddress": "SKYLINK PO Box 30245, Lilongwe, Malawi",  // NEW
    "collectionFeeRuleCode": "CM",                              // NEW
    "disbursementFeeRuleCode": "CM",                            // NEW
    "organisationId": "FYH0NTVW0DXK",
    "levelNumber": 1,
    "capturedBy": "admin@example.com"
}'

Response Body — The response now returns full merchant details:

{
  "merchantAccountNumber": 53494120,
  "accountBalance": 51027168.89,                            // NEW
  "revenueAmount": 0.00,                                    // NEW
  "dateCreated": "2025-11-20T09:11:55.405442",              // NEW
  "statusCode": "A",                                        // NEW
  "statusName": "Active",                                   // NEW
  "levelName": "Initiator Only",                            // NEW
  "categoryName": "Other Services",                         // NEW
  "classificationCode": "0021",                             // NEW
  "classificationName": "Services",                         // NEW
  "collectionFeeRuleName": "Charge Fees To The Merchant",   // NEW
  "disbursementFeeRuleName": "Charge Fees To The Merchant", // NEW
  "accountName": "SkyLink Aviation Services",
  "currencyCode": "MWK",
  "categoryCode": "8352",                                   // NEW
  "postalAddress": "FAKE ADDRESS, P.O. BOX 1234567, MALAWI",// NEW
  "collectionFeeRuleCode": "CM",                            // NEW
  "disbursementFeeRuleCode": "CM",                          // NEW
  "organisationId": "FYH0NTVW0DXK",
  "levelNumber": 1,
  "capturedBy": "admin@example.com"
}

Update Merchant

Request Body — The request now includes additional fields:

curl -X POST "https://api.onekhusa.com/sandbox/v1/merchants/accounts/update" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  -d '{
  "accountName": "SkyLink Aviation Services",
  "currencyCode": "MWK",
  "categoryCode": "8352",                               // NEW
  "postalAddress": "P.O. Box 30245, Lilongwe, Malawi",  // NEW
  "collectionFeeRuleCode": "CC",                        // NEW
  "disbursementFeeRuleCode": "CM",                      // NEW
  "organisationId": "FYH0NTVW0DXK",
  "levelNumber": 3,
  "capturedBy": "admin@example.com",
  "merchantAccountNumber": 35253486
}'

Get All Merchants

Response Body — The response now includes additional fields:

[
  {
    "merchantAccountNumber": 35253486,
    "accountBalance": 120422559.90,                              // NEW
    "revenueAmount": 0.00,                                       // NEW
    "dateCreated": "2025-11-17T10:24:36.062895",                 // NEW
    "statusCode": "A",                                           // NEW
    "statusName": "Active",                                      // NEW
    "levelName": "Initiator Only",                               // NEW
    "categoryName": "Other Services",                            // NEW
    "classificationCode": "0021",                                // NEW
    "classificationName": "Services",                            // NEW
    "collectionFeeRuleName": "Charges Fee To The Merchant",      // NEW
    "disbursementFeeRuleName": "Charges Fee To The Merchant",    // NEW
    "accountName": "SkyLink Aviation Services",
    "currencyCode": "MWK",
    "categoryCode": "8352",                                       // NEW
    "postalAddress": "FAKE ADDRESS, P.O. BOX 1234567, MALAWI",    // NEW
    "collectionFeeRuleCode": "CM",                                // NEW
    "disbursementFeeRuleCode": "CM",                              // NEW
    "organisationId": "FYH0NTVW0DXK",
    "levelNumber": 1,
    "capturedBy": "user@example.com"
  }
]

Get Merchant

Response Body — The response now includes additional fields:

{
  "accountName": "SkyLink Aviation Services",
  "currencyCode": "MWK",
  "categoryCode": "8352",                                     // NEW
  "postalAddress": "FAKE ADDRESS, P.O. BOX 1234567, MALAWI",  // NEW
  "organisationId": "351X9LQ5QZU4",
  "merchantAccountNumber": 53179887,
  "accountBalance": 120422559.90,                             // NEW
  "revenueAmount": 0.00,                                      // NEW
  "statusCode": "A",                                          // NEW
  "statusName": "Active",                                     // NEW
  "levelNumber": 1,
  "levelName": "Initiator Only",                              // NEW
  "categoryName": "Other Services",                           // NEW
  "classificationCode": "0021",                               // NEW
  "classificationName": "Services",                           // NEW
  "collectionFeeRuleCode": "CM",                              // NEW
  "collectionFeeRuleName": "Charge Fees To The Merchant",     // NEW
  "disbursementFeeRuleCode": "CM",                            // NEW
  "disbursementFeeRuleName": "Charge Fees To The Merchant",   // NEW
  "capturedBy": "user@example.com",
  "dateCreated": "2025-11-17T10:24:36.062895"                 // NEW
}

Disbursements

Single Disbursements Reorganisation

Added Single Disbursements Overview page documenting the reorganised structure.

Banks and Mobile Wallets — Standard single payouts to bank accounts and mobile wallets. The following endpoints have been moved to this section:

Intra-Organisation — Transfers between accounts within the same organisation:

Added Add Intra-Org Transaction endpoint for initiating a transfer between accounts within the same organisation.
Added Review Intra-Org Transaction endpoint for reviewing an intra-organisation transfer before approval.
Added Approve Intra-Org Transaction endpoint for approving a pending intra-organisation transfer.
Added Reject Intra-Org Transaction endpoint for rejecting an intra-organisation transfer.

Inter-Organisation — Transfers between accounts across different organisations:

Added Add Inter-Org Transaction endpoint for initiating a transfer between accounts across different organisations.
Added Review Inter-Org Transaction endpoint for reviewing an inter-organisation transfer before approval.
Added Approve Inter-Org Transaction endpoint for approving a pending inter-organisation transfer.
Added Reject Inter-Org Transaction endpoint for rejecting an inter-organisation transfer.

Transactions Inquiry — The following endpoints have been moved to the Transactions Inquiry section:

Webhooks

Added Webhook Events reference page with complete event code listings for collections, batch disbursements, and single disbursements.

Collection Webhooks

Added Webhooks Overview documenting the event-driven architecture, HMAC-SHA512 signature verification, idempotent handling, and retry circuit breaker with exponential backoff.
Added Account Top-Up Webhook event documentation.
Added Request-to-Pay Webhook event documentation.

Batch Disbursement Webhooks

Added Batch Disbursement Webhooks Overview documenting batch disbursement webhook events.
Added Batch Upload Webhook event documentation.
Added Batch Transfer Webhook event documentation.

Single Disbursement Webhooks

Added Single Disbursement Webhooks Overview documenting single disbursement webhook events.
Added Payout Webhook event documentation.

Verify Webhook

Updated Verify Webhook with new implementation using HMAC-SHA512 signature verification, timing-safe comparison, and code samples in C#, PHP, and Node.js.

Management

Webhook management endpoints have been moved to the Management section:

Merchant Accounts

Added Get organisation Merchants endpoint.

Test Your Integration

Added Simulate Custom Payment endpoint for simulating custom payment scenarios where customers provide a reference (e.g., invoice number) instead of using the standard Request to Pay flow.
Added Simulate Single Disbursement Reversal endpoint for Simulating Single Disbursement Reversal in the sandbox environment.
Added Simulate Payment Reversal endpoint for simulating payment reversals in the sandbox environment.

C# SDK

These changes are available in OneKhusa.SDK 2026.1.5.4 version.

Static Maintenance

Added Get Currencies SDK method documentation.
Added Get Countries SDK method documentation.

​New Section: Getting Started

​API updates

​Bill Payments

​Merchants

​Create Merchant

​Update Merchant

​Get All Merchants

​Get Merchant

​Disbursements

​Single Disbursements Reorganisation

​Webhooks

​Collection Webhooks

​Batch Disbursement Webhooks

​Single Disbursement Webhooks

​Verify Webhook

​Management

​Merchant Accounts

​Test Your Integration

​C# SDK

​Static Maintenance