Glossary
Definitions for key terms used throughout the PayOnUs API documentation.
Merchant ID
A unique identifier assigned to your merchant account. It identifies you as the top-level account holder on the PayOnUs platform.
Where to find it: Click the Profile icon in the top-right corner of the Merchant Dashboard. Your Merchant ID is displayed on the profile page.
Used in: Wallet endpoints (/api/v1/merchants/{merchantId}/wallets), wallet transaction queries, and other merchant-scoped APIs.
Business ID
A unique identifier assigned to a business entity created under your merchant account. A single merchant account can have multiple businesses. Most transaction and payout endpoints require a businessId to scope the operation to a specific business.
Where to find it: Navigate to the Business section on the dashboard. Toggle Test Mode OFF to view the Business IDs.
Used in: Virtually all payin and payout API requests.
ONUS Reference (onusReference)
A system-generated transaction reference assigned by PayOnUs to every transaction. It is unique, immutable, and serves as the canonical identifier for a payment or transfer on the PayOnUs platform.
Format examples:
- ONUS-NUB-4823916750234-01012026-090015 (Bank Transfer Payin)
- ONUS-CARD-5934827610345-01012026-091230 (Card Payin)
- ONUS-MMO-6045938721456-01012026-092445 (Mobile Money Payin)
- ONUS-EFT-7156049832567-01012026-093700 (EFT Payin)
- ONUS-TRNF-8267150943678-02012026-100015 (Transfer/Payout)
Always store the onusReference alongside your own merchantReference. It is required for transaction status queries (TSQ), reconciliation, and support escalations.
Merchant Reference (merchantReference)
A unique reference string generated by your system and passed in the API request when creating a transaction. It identifies the transaction in your own records.
Uniqueness: Must be unique per transaction within your business. Re-using a reference will result in a 409 Conflict error.
Access Token
A short-lived Bearer token used to authenticate all API requests. Generated by calling POST /api/v1/access-token with your Client ID and Client Secret. Expires after approximately 24 hours (expires_in seconds). Use the Sandbox base URL for sandbox tokens and the Production base URL for live tokens.
Client ID / Client Secret
API credentials tied to your merchant account and environment. Retrieved from Settings → API Credentials on the Merchant Dashboard. Used exclusively to generate access tokens — never included in end-user-facing code.
Webhook Verification Key
A secret string set by you in Settings → Webhook Verification Key on the Merchant Dashboard. Used server-side to verify the SHA-256 signature (hash header) attached to every incoming webhook notification, confirming the payload originated from PayOnUs.
Test Mode
A dashboard toggle that switches the active environment between Sandbox (Test Mode ON) and Production (Test Mode OFF). API credentials, webhook settings, and IP whitelist rules are separate per environment.
ONUS Reference Prefixes
| Prefix | Transaction Type |
|---|---|
ONUS-NUB-, ONUS-CNUB |
Bank Transfer Payin (Dynamic Account) |
ONUS-FNUB- |
Fixed Account Payin |
ONUS-CARD-, ONUS-CCARD- |
Card Payin |
ONUS-MMOH-, ONUS-MMOL- |
Mobile Money Payin |
ONUS-EFT- |
EFT Payin |
ONUS-TRNF- |
Payout (Bank Transfer, MoMo, EFT) |
ONUS-WTRNF- |
Wallet-to-Wallet Transfer |
ONUS-STTL- |
Settlement Credit to Wallet |