FAQ & Features Explained
Frequently asked questions about Africa payment orchestration, mobile money API integration, MTN MoMo API, M-Pesa API, Airtel Money API, and local payment methods in Africa.
Everything you need to know about JGME Pay's payment orchestration platform Africa, mobile money API integration, and processing alternative payment methods (APM) across African markets.
Getting Started
JGME Pay is a payment orchestration platform Africa and mobile money payment aggregator built specifically for African markets. We enable businesses to accept and disburse payments across 14+ African countries through a single payment orchestration API integration.
Our platform supports all major alternative payment methods (APM) and local payment methods in Africa:
- Mobile Money API: MTN MoMo, Orange Money, Airtel Money, M-Pesa, Wave, Moov
- Bank Transfers: Direct bank payments in Nigeria, Kenya, South Africa
- Cards: Visa, Mastercard via partner gateways
- Digital Wallets: Opay, PalmPay, and others
Key Africa mobile money API integrations include:
- MTN MoMo API integration across 10+ countries
- M-Pesa API for Kenya and Tanzania
- Airtel Money API for pan-African coverage
- Wave Money integration for Senegal, Ivory Coast, and more
With one multi-PSP integration, you can process payments across all these methods and markets with smart payment routing Africa capabilities.
JGME Pay runs a single live environment at https://api.jgmepay.com,
managed from https://merchant.jgmepay.com.
Every transaction is real. Validate your integration with the smallest amounts your providers accept before scaling up.
Our KYB (Know Your Business) requirements vary by business type, but typically include:
For Companies:
- Certificate of Incorporation
- Memorandum & Articles of Association
- Board Resolution authorizing payment processing
- Valid ID of Directors/UBOs
- Proof of Business Address
- Bank Statement (last 3 months)
For Sole Proprietors:
- Business Registration Certificate
- Valid Government ID
- Proof of Address
- Bank Statement
Processing Time: 1-5 business days
We offer relaxed KYB requirements compared to direct MNO integrations. Some merchants have completed onboarding in as little as 5 minutes for straightforward applications.
Mobile Money API Explained
Mobile money is a core alternative payment method (APM) where users pay directly from their mobile wallet (MTN MoMo, M-Pesa, Orange Money, Airtel Money, Wave, etc.) without needing a bank account or card. This is the most popular local payment method in Africa.
The typical payment flow using our mobile money API:
sequenceDiagram
participant Customer
participant Merchant
participant JGME Pay
participant MNO
Merchant->>JGME Pay: Create checkout session
JGME Pay-->>Merchant: Return checkout URL
Merchant->>Customer: Redirect to checkout
Customer->>JGME Pay: Select mobile money, enter phone
JGME Pay->>MNO: Initiate payment request
MNO->>Customer: Send STK Push / USSD prompt
Customer->>MNO: Enter PIN to authorize
MNO-->>JGME Pay: Payment confirmed
JGME Pay->>Merchant: Webhook notification
JGME Pay->>Customer: Redirect to success URLThe entire process typically takes 30-60 seconds from initiation to confirmation.
These are two methods MNOs use to prompt customers to authorize payments through their mobile money API:
STK Push (SIM Toolkit Push)
- How it works: A payment prompt is automatically "pushed" to the customer's phone
- User experience: Customer sees a pop-up asking them to enter their PIN
- Supported by: M-Pesa API (Kenya, Tanzania), some MTN markets
- Pros: Seamless, no dialing required
- Cons: Requires phone to be on and have signal
USSD (Unstructured Supplementary Service Data)
- How it works: Customer dials a code or receives a session-based menu
- User experience: Customer navigates menu and enters PIN
- Supported by: MTN MoMo API, Orange Money, Airtel Money API
- Pros: Works on basic phones, no data required
- Cons: More steps for customer
Provider Authorization (Merchant-Initiated)
- How it works: Payment request sent directly via mobile money API, MNO prompts customer
- Supported by: Most alternative payment method providers in West Africa
- Pros: Consistent experience across channels
JGME Pay's payment orchestration API automatically selects the appropriate authorization method based on the provider and country. You don't need to handle this logic—just call our API and we manage the mobile money integration Africa complexity.
When a customer pays via mobile money through JGME Pay:
Step 1: Initiation
- Customer selects mobile money as payment method
- Enters their mobile money phone number
- Clicks "Pay"
Step 2: Authorization
- Customer receives an STK push notification OR USSD prompt on their phone
- The prompt shows: merchant name, amount, and reference
- Customer enters their mobile money PIN to authorize
Step 3: Confirmation
- Customer sees "Payment Successful" on their phone
- Receives SMS confirmation from MNO
- Redirected back to merchant's success page
Typical Timing:
| Stage | Duration |
|---|---|
| Initiation to prompt | 2-5 seconds |
| Customer authorization | 10-30 seconds |
| Confirmation callback | 1-3 seconds |
| Total | 15-45 seconds |
Some MNO integrations support pre-authorization, where the customer pre-approves a payment before the merchant initiates it.
How it works:
- Customer visits MNO app/USSD and generates a pre-authorization code
- Customer provides this code to the merchant
- Merchant includes
preAuthorisationCodein the API request - Payment is processed without additional prompts
Supported markets:
- Orange Burkina Faso
- Orange Senegal
Pre-authorization availability depends on the specific MNO and market. Contact support for the latest supported configurations.
Transaction Processing
JGME Pay transactions can have the following statuses:
| Status | Description | Final? | Action Required |
|---|---|---|---|
queued | Payment Queued for Processing | ❌ | Wait for webhook |
pending | Payment initiated, awaiting customer authorization | ❌ | Wait for webhook |
processing | Customer authorized, MNO processing | ❌ | Wait for webhook |
success | Payment completed successfully | ✅ | Fulfill order |
rejected | Payment failed (see error code) | ✅ | Show retry option |
failed | Payment failed (see error code) | ✅ | Show retry option |
expired | Customer didn't authorize in time | ✅ | Show retry option |
reversed | Funds returned to customer | ✅ | Update records |
Never fulfill orders based on pending or processing status. Always wait for a final status (success, failed, expired) before taking action.
Our Smart Reconciliation Engine ensures every transaction reaches a final status:
How it works:
- Real-time monitoring: We track every transaction from initiation
- Automatic polling: For pending transactions, we poll MNO status APIs
- Statement reconciliation: We download and reconcile MNO statements
- Timeout handling: Transactions that exceed timeout are marked appropriately
- Callback retry: We retry webhook notifications until acknowledged or after 60 minute
Result: No transaction is left in pending state indefinitely. Every payment reaches a conclusive status (success, failed, or expired) within the provider's timeout window (typically 5-60 minutes).
If you see a transaction stuck in "pending" on your dashboard, our reconciliation engine is already working to resolve it. Check back in 5-60 minutes, or contact support if it persists beyond 60 minutes.
Each MNO has different timeout windows for customer authorization:
| Provider | Timeout | Notes |
|---|---|---|
| M-Pesa (Kenya) | 60 seconds | STK push expires quickly |
| MTN MoMo | 5-15 minutes | Varies by country |
| Orange Money | 5-10 minutes | USSD session timeout |
| Airtel Money | 5-10 minutes | Standard timeout |
| Wave | 5 minutes | App-based confirmation |
If a customer doesn't authorize within the timeout window, the transaction will be marked as expired and you'll receive a webhook notification.
When a transaction fails, check the errorCode and errorMessage in the response/webhook:
Common failure reasons:
| Error | Cause | Resolution |
|---|---|---|
INSUFFICIENT_FUNDS | Customer's wallet balance too low | Ask customer to top up |
WRONG_PIN | Customer entered incorrect PIN | Retry with correct PIN |
TIMEOUT | Customer didn't respond in time | Retry the transaction |
ACCOUNT_LOCKED | Customer's wallet is locked | Customer contacts MNO |
INVALID_PHONE | Phone number not registered for mobile money | Verify phone number |
DAILY_LIMIT_EXCEEDED | Customer exceeded daily transaction limit | Try smaller amount or wait |
SYSTEM_ERROR | MNO technical issue | Retry after a few minutes |
Best practices:
- Show user-friendly error messages
- Offer retry option for retriable errors
- Log all failed transactions for analysis
- Contact support for persistent
SYSTEM_ERRORissues
Webhooks & Callbacks
Webhooks notify your server about transaction status changes in real-time.
Setup steps:
- Go to Dashboard → Settings -> Security -> API Keys and Webhooks
- Enter your webhook endpoint URL (e.g.,
https://yoursite.com/jgmepay/webhook) - Click Save
Requirements for your webhook endpoint:
- Must be publicly accessible (no localhost)
- Must use HTTPS (SSL certificate required)
- Must return HTTP 200 within 30 seconds
- Should be idempotent (handle duplicate calls)
You can also specify a webhook URL per-transaction by including the webhook parameter in your API request. This overrides the default webhook for that specific transaction.
When a transaction status changes, we send a POST request to your webhook URL:
{
"event": "payment.completed",
"timestamp": "2025-02-06T10:30:00Z",
"data": {
"reference": "ORDER-12345",
"checkoutId": "chk_abc123xyz",
"amount": 5000,
"currency": "NGN",
"country": "NG",
"status": "success",
"provider": "mtn-momo-nigeria",
"channel": "mobile-money",
"user": {
"email": "customer@example.com",
"phoneNumber": "08012345678"
},
"paidAt": "2025-02-06T10:30:00Z",
"metadata": {
"orderId": "your-custom-data"
}
}
}Event types:
payment.completed- Payment successfulpayment.failed- Payment failedpayment.expired- Payment timed outdisbursement.completed- Disbursement successfuldisbursement.failed- Disbursement failed
Best practices for webhook handling:
app.post('/jgmepay/webhook', async (req, res) => {
const event = req.body;
// 1. Acknowledge immediately (prevents timeout)
res.status(200).send('OK');
// 2. Process asynchronously
processWebhookAsync(event);
});
async function processWebhookAsync(event) {
// 3. Check if already processed (idempotency)
const existing = await db.findTransaction(event.data.reference);
if (existing?.status === event.data.status) {
return; // Already processed
}
// 4. Verify transaction via API (optional but recommended)
const verified = await jgmepay.verifyTransaction(event.data.reference);
// 5. Update your records
await db.updateTransaction(event.data.reference, {
status: verified.status,
paidAt: verified.paidAt
});
// 6. Take action
if (verified.status === 'success') {
await fulfillOrder(event.data.reference);
}
}Critical: Always return HTTP 200 quickly. If your endpoint times out or returns an error, we'll retry the webhook. Implement idempotency to handle duplicate deliveries.
We implement automatic retry logic for failed webhook deliveries:
Retry schedule:
- Attempt 1: Immediate
- Attempt 2: 1 minute later
- Attempt 3: 5 minutes later
- Attempt 4: 30 minutes later
- Attempt 5: 1 hours later
After all retries fail:
- Transaction status is still updated in our system
- You can always query transaction status via API
- Replay the webhooks from your dashboard
Set up monitoring for your webhook endpoint and dashboard alerts for failed deliveries. You can also implement a polling fallback to check for missed webhooks.
Settlement & Disbursements
Settlement times vary by country and payment method:
| Country | Method | Settlement |
|---|---|---|
| Nigeria | Bank Transfer | T+1 (Next business day) |
| Nigeria | Mobile Money | T+1 to T+2 |
| Kenya | M-Pesa | T+1 |
| Ghana | All methods | T+1 to T+2 |
| Ivory Coast | Mobile Money | T+2 to T+3 |
| Other CFA Zone | Mobile Money | T+2 to T+3 |
T = Settlement Request Day
Settlements are processed to your designated bank account or mobile money wallet as configured in your merchant profile.
Yes! JGME Pay supports disbursements to:
- Mobile Money Wallets: Send to any supported MNO
- Bank Accounts: Nigeria, Kenya, South Africa, and more
- Bulk Disbursements: Process multiple disbursements in one API call
Process:
- Validate recipient (phone number or bank account)
- Submit disbursement request
- Receive webhook on completion
Typical processing times:
- Mobile Money: 30 seconds - 5 minutes
- Bank Transfer: Same day - Next business day
See our Disbursements Guide for full documentation.
You can check your wallet balances via:
Dashboard:
- Login to your merchant dashboard
- View balances on the home screen
- You can switch country by using the switch on the top right to view balances in a different country
API:
curl --location 'https://api.jgmepay.com/billing/v1/wallets' \
--header 'client-id: YOUR_CLIENT_ID' \
--header 'client-secret: YOUR_CLIENT_SECRET'Response shows balances per currency:
{
"data": [
{ "currency": "NGN", "country": "NG", "balance": 1500000 },
{ "currency": "KES", "country": "KE", "balance": 85000 },
{ "currency": "XOF", "country": "CI", "balance": 2500000 }
]
}Technical Integration - Payment Orchestration API
JGME Pay does not support decimal amounts. Send integer values only in minor units.
Examples:
| Display Amount | Value to Send |
|---|---|
5000.50 NGN | 500050 |
100.00 GHS | 10000 |
1000 KES | 100000 |
10000 XOF | 1000000 |
5000 XAF | 500000 |
Important: Sending decimals (for example 1250.75) will cause validation or provider failures. Send minor-unit integers only (for example 125075).
See Amount Specification for full conversion guidance, and Supported Providers for provider limits.
Phone numbers should be in international format without the plus sign:
| Country | Format | Example |
|---|---|---|
| Nigeria | 234XXXXXXXXXX | 2348012345678 |
| Kenya | 254XXXXXXXXX | 254712345678 |
| Ghana | 233XXXXXXXXX | 233201234567 |
| Ivory Coast | 225XXXXXXXXXX | 2250512345678 |
| Cameroon | 237XXXXXXXXX | 237612345678 |
Do NOT include:
- Plus sign (+)
- Spaces or dashes
- Leading zeros after country code
Example:
// ✅ Correct
{ "phoneNumber": "2348012345678" }
// ❌ Wrong
{ "phoneNumber": "+234-801-234-5678" }
{ "phoneNumber": "08012345678" }The Direct Charge payment orchestration API allows you to initiate payments directly without redirecting customers to a checkout page. This is useful for:
- Server-to-server payments: When you've already collected customer details for mobile money API charges
- Recurring payments: Charging saved payment methods
- Mobile app integrations: Native mobile money integration Africa experiences
How it works with MTN MoMo API, M-Pesa API, and other mobile money:
curl --location 'https://api.jgmepay.com/payments/v1/payments/direct-charge' \
--header 'client-id: YOUR_CLIENT_ID' \
--header 'client-secret: YOUR_CLIENT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"provider": "mtn-momo-nigeria",
"amount": 5000,
"reference": "ORDER-12345",
"customerInput": {
"phoneNumber": "2348012345678"
},
"webhook": "https://yoursite.com/webhook"
}'The customer receives the STK push / USSD prompt directly on their phone through the Africa mobile money API.
Yes! Bring Your Own Keys (BYOK) or Hybrid Orchestration is our multi-PSP integration Africa approach that lets you use your existing MNO contracts through JGME Pay's payment orchestration platform infrastructure.
How it works:
- You maintain direct contracts with MNOs (e.g., MTN MoMo API, M-Pesa API, Orange Money)
- Securely input your MNO’s API keys, this gets tokenised and stored encrypted and not visible to JGME Pay
- We route transactions through your MNO wallet/account/OVA using our smart payment routing engine
- You keep your negotiated rates for each mobile money API
Benefits of multi-PSP integration:
- Lower fees (your negotiated rates)
- Maintain provider relationships
- Combined coverage (your contracts + our partnerships)
- Single dashboard for all alternative payment methods (APM)
- Enterprise payment orchestration Africa capabilities
Setup: Contact commercial@jgmepay.com to configure hybrid orchestration for your Africa payment orchestration account.
JGME Pay's smart payment routing Africa technology provides automatic failover:
How it works:
- When a primary provider fails, we automatically try backup rails
- Multi-PSP integration ensures multiple providers per country for redundancy
- Real-time monitoring detects outages within seconds
- Traffic is re-routed without merchant intervention
Example for mobile money API failover:
- Primary: MTN MoMo API direct integration
- Backup 1: MTN via aggregator
- Backup 2: Alternative mobile money payment aggregator route
Result: 99.99% uptime and higher transaction success rates across all local payment methods in Africa.
You can also configure routing preferences in your dashboard if you want to prioritize certain alternative payment methods for cost or performance reasons.
Security & Compliance
Yes. JGME Pay is PCI DSS compliant and undergoes regular security assessments:
- PCI DSS Compliance: We are strictly compliant with the PCIDSS standard for card security
- Quarterly ASV Scans: External vulnerability assessments by certified consultants
- Annual Penetration Testing: Third-party security audits
- End-to-End Encryption: All data encrypted in transit (TLS 1.2+) and at rest
You can request our compliance certificates via compliance@jgmepay.com.
We take data privacy seriously:
- GDPR-aligned practices: Even for non-EU data
- Data minimization: We only collect what's necessary
- Encryption: All PII encrypted at rest and in transit
- Access controls: Role-based access with audit logging
- Retention policies: Data retained per regulatory requirements
Customer data we store:
- Phone numbers (for payment processing)
- Email addresses (for notifications)
- Transaction history (for reconciliation)
We do NOT store:
- Mobile money PINs
- Card CVVs (tokenized immediately)
- Customer wallet balances
JGME Pay includes built-in fraud detection:
- Velocity checks: Detect unusual transaction patterns
- Device fingerprinting: Identify suspicious devices
- Geolocation analysis: Flag location mismatches
- Amount thresholds: Configurable limits per merchant
- Blacklist management: Block known bad actors
You can also:
- Set custom transaction limits in your dashboard
- Enable additional verification for high-value transactions
- Access fraud analytics and reports
Troubleshooting
Transactions may appear pending for several reasons:
| Cause | Resolution |
|---|---|
| Customer hasn't authorized yet | Wait for customer to enter PIN |
| MNO processing delay | Usually resolves within 5-15 minutes |
| Network connectivity issues | Our reconciliation engine will resolve |
| STK push not received | Customer may need to retry |
What to do:
- Wait 5-15 minutes for auto-resolution
- Check transaction status via API
- If stuck > 30 minutes, contact support
Our reconciliation engine ensures all transactions reach final state—no manual intervention required in most cases.
This error means your API credentials are invalid:
Common causes:
- Using credentials that do not match the base URL you are calling
- Typo in
client-idorclient-secret - Credentials were regenerated and old ones are being used
- Missing required headers
Solution:
- Verify you're using the correct environment URLs
- Re-copy credentials from Dashboard → Settings → API Keys
- Ensure headers are exactly:
client-idandclient-secret(notclientId)
# Correct header format
--header 'client-id: abc123' \
--header 'client-secret: xyz789'