​
Prerequisites

Before you begin, ensure you have:
  • A valid email address for account registration
  • Basic understanding of REST APIs and JSON

​
Step 1: Portal Setup

This step covers all the initial configuration you need to do in the OneKhusa web portal. You’ll create your account, set up your merchant profile, obtain necessary credentials, and configure webhooks for real-time notifications. This setup is required before you can make any API calls.

​
1.1 Register Your Account

  1. Visit OneKhusa Portal and register your user account

​
1.2 Merchant Account Setup

  1. Use Default Merchant: Use the automatically created merchant account, OR
  2. Create New Merchant: Go to Merchants → Add a new merchant account, if needed
  3. Add Settlement Account: Go to Merchants → View Merchant → Add Bank Account, this is required for disbursement and collection transactions

​
1.3 Get Required Identifiers

  1. Organization ID: Navigate to Settings → Profile page
    • Copy your Organization ID and do not share with anyone (only visible for merchant administrator and PSP/PSO administrator user profiles)
  2. Merchant Account Number: Found under Merchants menu

​
1.4 API Key Setup

  1. Go to Developers → API Keys
  2. Create at least one API key pair (API Key + API Secret)
  3. Save these credentials securely - you’ll need them for authentication

​
1.5 Webhook Configuration (Optional)

If you want real-time notifications:
  1. Go to Developers → Webhooks
  2. Create webhooks for events you want subscribed to for your system to get notified such as:
    • payment.success - Successful payment collections
    • payout.success - Successful disbursements
    • batch.received - Batch disbursement received
    • See Webhook Events for complete list

​
1.6 Fund Your Account

  1. Go to Fake Data → Merchant Topup
  2. Load test funds to merchant account with maximum amount of 5,000,000,000.00 of account balance
  3. This enables you to test disbursement transactions

​
Step 2: API Integration

Once your portal setup is complete, you can start making API calls. This step covers authentication, testing disbursements (both batch and single transactions), and accepting payments through collections. You’ll learn how to get an access token and perform your first transactions.

​
2.1 Get Access Token

First, authenticate to get an access token. See the Get Access Token documentation for detailed examples and implementation.

​
2.2 Test Disbursements

You have two options for disbursements as follows and if you have subscribed to webhook events, you will receive the notifications to your system:
Connector Definition: A connector refers to a bank, mobile money operator, SACCO, MFI, or digital wallet that processes payments through OneKhusa.

​
Option A: Batch Disbursements

  1. Get Connectors: First call Get All Connectors to see available payment methods
  2. Download Sample File: Go to Fake Data → Download Sample Disbursement in either Microsoft Excel or CSV format. This is applicable for Batch File Uploads.
  3. Fill Transaction Data: Add or remove or change beneficiary details in the file generated to your preference
  4. Upload Batch: Use either:

​
Option B: Single Disbursements

  1. Get Connectors: First call Get All Connectors to see available payment methods
  2. Create Transaction: Use Add Single Transaction with connector details

​
2.3 Test Collections (Accepting Payments)

Follow these steps to test how your system can accept payments processed by OneKhusa payment gateway.

​
1. Understand the flow

Read the Accepting Payments – Overview to understand how customer payments move from bank accounts and mobile wallets into your OneKhusa merchant account, and how your system receives webhook notifications for processed payments.

​
2. Subscribe to collection webhooks

To manage webhooks for your merchant system, login to portal and do the following:
  • Go to Developers → Webhooks in the portal.
  • Create a webhook pointing to your endpoint and subscribe to events documented in the collection webhook, such as payrequest.success (and any others you need).

​
3. Use Request To Pay to initiate a payment

  • From your merchant system, call the Request To Pay endpoint to generate a Timed Account Number (TAN) with transaction amount and unique reference number tied to a transaction.
  • The TAN will be used by the customer to pay, and it expires after 15 minutes.
  • Upon successful payment, your system will receive webhook notification.

​
4. Simulate the customer payment in sandbox

Use the Simulate Accept Request To Pay endpoint to imitate a customer paying through bank account or mobile wallet using the TAN generated in step 3.
NOTE: This simulation works only if the request-to-pay transaction was already initiated otherwise you will get an error that the transaction does not exist.

​
5.Topup merchant account in sandbox

Use the Merchant Account Topup endpoint to simulate the topping up of funds from a bank account or mobile wallet to your merchant account.
NOTE: This is important if you want to test either batch disbursements or single disbursements features otherwise without funds, you will not be able to pay out funds to beneficiaries.

​
6. Handle the webhook notification

When the simulated payment is successful, OneKhusa sends a webhook notification (for example, payrequest.success) to your subscribed collection webhook. In your system:
  • Receive this webhook notification.
  • Verify the webhook notification payload. DO NOT trust webhook notifications.
  • Match it to your original unique reference or stored TAN and then mark the transaction as paid.

​
7. Move to live payments

In production environment, instead of simulating with fake collection transaction endpoints, real customers pay through their bank or MNO apps (USSD, WhatsApp, Internet Banking or mobile app) using the TAN generated.

​
Step 3: Production Deployment

After successfully testing in the sandbox environment, follow the steps below to have access to the production environment to perform live transactions:
  • Funding: You can only top up through connector channels (USSD, Mobile App, Internet Banking)
  • Compliance: Submit required KYC documents
  • Base URL: Switch to https://api.onekhusa.com/live/v1
  • Webhooks: Update webhook URLs to production endpoints

​
Next Steps

  1. Explore APIs: Review the complete API Reference
  2. Test Webhooks: Set up webhook endpoints to receive real-time notifications
  3. Monitor Transactions: Use analytics endpoints to track transaction metrics