Introduction
Welcome to the OrzPay Developer Portal
Build and connect with OrzPay’s digital payment infrastructure using our APIs and developer tools. This documentation guides you through authentication, payment requests, transaction processing, webhooks, responses, and integration best practices.
The overview below illustrates how OrzPay connects customers, merchants, banks, and payment services to facilitate secure digital transactions.
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
API Reference
Payments API
Initiate Payment
Creates a payment request using Mobile Money, QR Code, Wallet, or Virtual Card.
Verify Payment
Retrieve the current payment status using a Transaction Reference.
Cancel Payment
Cancel a pending payment before processing is completed.
Refund Payment
Issue full or partial refunds for completed transactions where applicable.
Mobile Money API
Supports direct integration with:
- MTN Mobile Money
- Airtel Money
Available Services
- Collections
- Disbursements
- Wallet Payments
- Merchant Payments
- Balance Enquiries
Wallet API
The Wallet API enables developers to manage customer wallets.
Available Operations
- Create Wallet
- Wallet Balance
- Transaction History
- Send Money
- Receive Money
- Wallet Statement
QR Payment API
The QR Payment API enables merchants to accept contactless payments.
Available Operations
- Generate Dynamic QR Code
- Verify QR Code
- Receive QR Payment
- Payment Confirmation
Bill Payment API
Allow customers to pay multiple service providers.
Supported Categories
- Utility Bills
- Water Bills
- Electricity
- Internet
- School Fees
- Television Subscriptions
Remittance API
The Remittance API allows secure domestic and international money transfers.
Supported Features
- Local Transfers
- Cross-border Transfers
- Beneficiary Validation
- Transfer Status
- Transfer History
Virtual Card API
Create and manage secure virtual payment cards.
Features include
- Create Virtual Card
- Freeze Card
- Block Card
- Card Balance
- Transaction History
- Card Limits
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.
API Endpoint Cards
/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.
Request Parameters Table
| 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.
Response Codes
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.
Webhooks
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.
SDKs, Testing Sandbox & Best Practices
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.
Integrated Examples
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.FAQ Knowledge Base
Technical integration guidelines and frequently asked development answers for the OrzPay platform.
Authorization header using the standard Bearer token schema format: Authorization: Bearer YOUR_SECRET_KEY.
UGX (Ugandan Shilling), KES (Kenyan Shilling), and TZS (Tanzanian Shilling). Additional settlement pathways are currently under active development.
GET request to our verification route mapping: /v1/payments/{transaction_id}.
HTTP 200 OK response.
insufficient_funds.
reference payload attribute field parameter. Our gateway tracks references and rejects duplicate execution commands to eliminate accidental billing events.
https://orzpay.com. No real funds move while interacting inside the sandbox.