Implementation Guide
This guide explains how to set up and configure your ZoPay integration, including how payment methods work, domain verification, and the payment flow architecture.
Gateway Configuration
Understanding Gateways
Payment gateways are the underlying payment methods that ZoPay supports. Currently, ZoPay supports two main gateways:
- MTN_MOMO - MTN Mobile Money
- ORANGE_MONEY - Orange Money
Each merchant account is enabled for the payment methods agreed with ZoPay (typically MTN Mobile Money and/or Orange Money). Gateway availability and limits are managed by ZoPay operations—not via a self-service screen in the dashboard.
Configuring a Gateway
If you need to change which gateways are enabled or adjust transaction limits, contact Help & Support from your merchant dashboard. The team will update your account configuration.
Domain Verification
Why Domain Verification?
Domain verification is a security feature that proves you own the domain you're claiming. It's required for production API access and prevents unauthorized domains from using your API keys. Only verified domains can be used in the x-zo-origin header.
Domain Verification Process
Our sandbox and production environment are completely separated from each other. You can invite anybody into the sandbox portal, they will not get access to any production information as part of the sandbox.
📦 Domain Verification Steps
- Add Your Domain
- Navigate to Domain Settings in your merchant dashboard
- Enter your domain (e.g., example.com)
- Click "Add Domain"
- You'll receive a verification token
- Add DNS TXT Record
- Log into your domain's DNS provider (GoDaddy, Cloudflare, Namecheap, etc.)
- Important for Vercel users: You cannot add DNS records to Vercel domains (*.vercel.app). You must use a custom domain and add the TXT record at your domain registrar (where you bought the domain), not in Vercel's DNS settings.
- Add a new TXT record:
- • Name:
_zopay - • Type: TXT
- • Value: [your verification token]
- • TTL: 3600 (or default)
- • Name:
- Wait for DNS Propagation
- Important: DNS changes can take 15-30 minutes (sometimes up to 48 hours) to propagate globally
- You must wait before clicking "Verify Domain" - if you click too soon, verification will fail
- Test the DNS record first using online tools (see Domain Verification Guide)
- You can check if the record has propagated with:
nslookup -type=TXT _zopay.example.com - Wait at least 15-30 minutes after adding the TXT record before attempting verification
- Verify Domain
- After waiting 15-30 minutes, return to your merchant dashboard
- Test the DNS record first using online tools (recommended - see Domain Verification Guide)
- Click "Verify Domain" next to your domain
- System will automatically check DNS records
- If token matches → Domain verified ✅
- If not found → Wait a bit longer (DNS may still be propagating) and try again
- Domain Ready
- Once verified, you can use this domain in the
x-zo-originheader - Verified domains are automatically allowlisted
- Once verified, you can use this domain in the
About TTL: TTL (Time To Live) determines how long DNS servers cache the record. A TTL of 3600 seconds (1 hour) means the record will be cached for 1 hour. After the TTL expires, the record can still be verified - TTL only affects caching, not the record's validity. You can verify your domain at any time after adding the DNS record, regardless of TTL.
Important Notes
- Only domain owners can add DNS records (proves ownership)
- DNS propagation may take 15-30 minutes
- You can verify multiple domains
- Domain verification is required for production (sandbox may be more lenient)
IP Allowlisting (Alternative to Domain Verification)
IP Allowlisting Overview
IP allowlisting is an alternative security method to domain verification. You can use either IP allowlisting OR domain verification (or both). If you use IP allowlisting, requests must come from allowed IP addresses.
This method is particularly useful for server-to-server integrations where domain verification isn't applicable, such as backend services or mobile applications.
How It Works
Configure allowed IP addresses or CIDR ranges in your merchant dashboard. Requests from non-allowlisted IPs are rejected with a 403 Forbidden response. This provides an additional layer of security by ensuring only requests from your known servers can access your API.
Understanding the Payment Flow
Quote-Based System
All payments in ZoPay start with creating a quote. The quote locks in fees for 15 minutes, ensuring you know exactly what you'll be charged. The quote must be used before expiry, and each quote can only be used once.
This quote-based approach provides price certainty and prevents fee fluctuations during the payment process.
Transaction States
Transactions in ZoPay go through several states:
- PENDING - Transaction has been initiated
- PROCESSING - Transaction is being processed by the gateway
- VERIFYING - Transaction is being verified
- SUCCESS - Transaction completed successfully
- FAILED - Transaction failed (check error details)
Transactions are asynchronous, meaning the API returns immediately after accepting the request. You should use webhooks or polling to check the final status of your transactions.
Idempotency
Use unique idempotency keys for each transaction. This prevents duplicate payments if a request is retried due to network issues or timeouts. The idempotency key must be unique per quote and helps ensure that retrying a request doesn't result in multiple charges.
Security Best Practices
- Protect your API keys and secret keys - never commit them to version control
- Use HTTPS for all API requests
- Implement proper error handling and retry logic
- Monitor your API usage and set up alerts for unusual activity
- Set up webhooks for real-time notifications
- Test thoroughly in sandbox before moving to production
- Keep your secret keys secure and rotate them periodically
- Use IP allowlisting or domain verification for additional security
Next Steps
Now that you understand the setup process, learn how to use the API:
- Domain Verification Guide - Complete guide to verifying your domain for production
- Using the API - Learn about authentication, headers, and making requests
- Collections Documentation - Learn how to accept payments
- Disbursements Documentation - Learn how to send payments