Quick Integration

​

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:

​

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:
   • Upload Batch File endpoint (for Excel/CSV files)
   • Upload Batch JSON endpoint (for JSON payloads)

​

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 (Accept Payments)

1. To simulate collection payment transaction, use fake merchant account topup feature
2. Monitor webhook notifications for real-time updates

​

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