Welcome to the OrzPay Developer Portal. This documentation explains how to integrate OrzPay payment services into websites, mobile applications, POS systems, and enterprise software.
Before initializing integration sequences targeting the OrzPay transaction clearing networks, confirm your application infrastructure ticks all required parameters:
All secure API interactions targeted at OrzPay processing servers must undergo validation checks. Authentication runs through the standard HTTP Header profiles using private Bearer Secret Tokens.
To safeguard balance allocations and consumer transaction records across external endpoints, strictly apply these security protection procedures:
- Keep API Secrets Confidential: Never commit raw secret values into public asset repositories or version control histories.
- Zero Frontend Exposure: Never bundle private authorization tokens inside client-side components (like JavaScript web bundles). Always execute queries from backend environments.
- Force Transport Security: Reject inbound non-SSL endpoints. Enforce TLS 1.2 or higher across target payment routes.
- Routine Token Rotation: Regularly cycle out operational access tokens through dashboards to limit risk exposure boundaries.
- Use Environment Controls: Inject all private access parameters straight out of secure background server systems (such as
.envfile structures).
Target transaction configurations down these respective cluster routes depending on the operational life stage of your digital solution platform:
Sandbox Mockup Gateway
https://orzpay.com
Production Core Gateway
https://orzpay.com
All requests directed toward OrzPay APIs must bear your secret key within the HTTP authorization headers header profile structure.
Endpoint used to generate a secure digital collection sequence spanning local infrastructure routing paths.
Interrogate the billing cluster engines directly to capture execution status updates asynchronously.
/v1/payments
Initiate a brand new customer payment request via secure localized transaction methods.
/v1/payments/{id}
Retrieve validation and absolute lifecycle confirmation records for specific transactions.
/v1/transfers
Send immediate real-time mobile liquidity settlements directly out to verified target numbers.
/v1/collections
Perform direct requests to settle pending balances directly from consumer digital assets.
/v1/qr/payments
Scan, parse, and confirm consumer retail network intents via encrypted localized optical symbols.
/v1/payments/{id}/refund
Return funds safely back into origin wallets from clear, auditable historic balances.
/v1/transactions
Pull historically processed items using complex parameters such as pagination boundaries.
/v1/wallet/balance
View absolute tracking parameters reflecting net working capital currently active.
/v1/webhooks
Define structural callback receptors to parse event responses in real-time.
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | Integer | Yes | Total processing value mapped as minor currency units. |
| currency | String | Yes | ISO-4217 Currency representation matrix designation code (e.g. UGX). |
| phone | String | Yes | The destination mobile subscriber dialing target configuration address. |
| provider | String | Yes | Telecom switching core processing networks identifier (MTN, AIRTEL). |
| reference | String | Yes | Unique string identifier mapped directly from your merchant ledger. |
| callback_url | String | No | Target processing URL location hook for asynchronous reporting. |
| HTTP Code | Status Text | Core Integration Meaning |
|---|---|---|
| 200 | OK | The execution call successfully resolved transactions without logic flags. |
| 201 | Created | Entities structurally provisioned into persistence layer records. |
| 400 | Bad Request | Malformed layout profiles or type validation limits encountered. |
| 401 | Unauthorized | Cryptographic validation checks failed or are completely missing headers. |
| 429 | Too Many Requests | API processing limits triggered. Please apply exponential backoff techniques. |
OrzPay delivers secure cryptographic payload blocks via webhook endpoints instantly upon resolution of background financial ledger interactions.
OrzPay uses standard HTTP status response codes to signal the outcome of incoming API requests. Codes in the 2xx range indicate success, 4xx range indicate request/validation validation issues, and 5xx range indicate backend system infrastructure errors.
| Code | Status | Meaning |
|---|---|---|
| 200 | OK | Request completed successfully. |
| 201 | Created | Transaction successfully created. |
| 202 | Accepted | Request accepted for processing. |
| 400 | Bad Request | Invalid request parameters. |
| 401 | Unauthorized | Invalid or missing authentication credentials. |
| 403 | Forbidden | Access denied to requested resource. |
| 404 | Not Found | Requested resource does not exist. |
| 409 | Conflict | Duplicate transaction hash or reference conflict. |
| 422 | Unprocessable Entity | Validation failed on resource payload fields. |
| 429 | Too Many Requests | Rate limit exceeded. Too many operations per window. |
| 500 | Internal Server Error | An unexpected server-side error occurred. |
| 502 | Bad Gateway | Upstream cellular switching service node error. |
| 503 | Service Unavailable | Service temporarily unavailable. Retry later. |
Transaction Status Codes: Beyond HTTP rules, processing states trace custom lifecycle tracking schemas inside payload data objects:
| Status | Meaning |
|---|---|
| PENDING | Transaction is being processed by the network provider. |
| SUCCESS | Transaction completed and funds settled successfully. |
| FAILED | Transaction failed or was rejected by the cellular network. |
| CANCELLED | Transaction was explicitly cancelled by the customer. |
| REFUNDED | Transaction was successfully reversed and refunded. |
| EXPIRED | Transaction confirmation request timed out. |
ERROR HANDLING
The OrzPay API returns meaningful HTTP response codes and descriptive error messages.
Common Errors
Invalid API Key
The supplied API credentials are invalid.
Unauthorized Access
Authentication failed.
Invalid Amount
Payment amount does not meet transaction requirements.
Network Timeout
The payment provider did not respond within the expected time.
Duplicate Transaction
The supplied transaction reference already exists.
Insufficient Balance
Customer wallet balance is insufficient.
When a request fails, OrzPay returns a standard HTTP status error code paired with a descriptive JSON payload to help developers troubleshoot validation or processing errors.
To ensure incoming webhook events are sent directly by OrzPay and not tampered with, calculate a digital signature on your server and compare it against the value in the header.
OrzPay sends secure webhook notifications to your registered endpoint whenever important payment events occur. This ensures your system can update order fulfillment records automatically without manually polling status tracking endpoints.
Accelerate your integration lifecycle. While our native core servers are running final optimization tests, download our pre-release informational boilerplate models:
Every developer account grants access to an isolated staging sandbox environment to simulate payments safely without moving real money.
- Base Sandbox URL:
https://orzpay.com - Toggle between live keys and sandbox test keys inside your dashboard.
- Simulate approved payments by using the keyword reference:
TEST_SUCCESS. - Simulate a declined payment by passing the keyword reference:
TEST_DECLINED.
Ensure a highly resilient connection between your merchant platform and our payment confirmation cluster routes:
- Idempotency Keys: Always include an original transaction reference header to prevent duplicate payments from network retries.
- Network Timeouts: Configure your HTTP client libraries to wait a minimum of 30 seconds before timing out connection tasks.
- Webhook Fail-safes: Program your system to return a
200 OKresponse instantly upon receiving webhooks, before running heavy internal processing tasks.
Review end-to-end processing scenarios below to design robust payment collection pathways on your commercial merchant application infrastructure.
Example 1: Accept a Mobile Money Payment
This workflow shows the complete asynchronous lifecycle of an MTN or Airtel Mobile Money collection call initialized from your customer checkout portal.
/v1/payments endpoint over an authorized security layer with transaction metadata details.Example 2: Send Money (Payouts & Transfers)
This workflow explains the architectural sequence used when your merchant platform triggers outbound bulk liquidity transfers directly to a recipient's Airtel or MTN mobile money wallet.
wallet.debited hits your platform's server listener interface.Example 3: Handling Failed Payments & Retry Intervals
This workflow shows how the client application architecture handles common cellular exceptions—like customer rejections or system timeouts—using exponential fallback polling loops.
FAILED.payment.failed event type down to your merchant platform's listener hook.GET /v1/payments/{id} request before timing out.Developers should perform all testing using the Sandbox environment before requesting Production access.
Sandbox Features
- Simulated payments
- Test callbacks
- Transaction verification
- Error simulation
- Wallet testing
- QR payment testing
Welcome to the OrzPay Developer Portal. This documentation explains how to integrate OrzPay payment services into websites, mobile applications, POS systems, and enterprise software.
Frequently Asked Questions
How do I obtain API credentials?
Register as a merchant or developer, complete verification, and generate your API keys from the Developer Dashboard.
What payment methods are supported?
OrzPay supports Mobile Money, QR Code payments, Digital Wallets, Virtual Cards, Bank Transfers, and Bill Payments.
Can I test before going live?
Yes. Developers receive Sandbox credentials for testing before Production approval.
How do webhooks work?
Whenever a payment status changes, OrzPay sends an HTTP POST notification to your registered callback URL.
Are API requests encrypted?
Yes. All API communication is protected using HTTPS and industry-standard encryption protocols.
Is there rate limiting?
Yes. API requests may be subject to rate limits to ensure platform stability and security.
Can I integrate multiple payment methods?
Yes. Developers can integrate Mobile Money, Wallet, QR Payments, Virtual Cards, and future banking services within one integration.