Frequently Asked Questions

To get started, create an account on our platform. Once registered, you'll have immediate access to the sandbox environment where you can test your integration. Navigate to your merchant dashboard to retrieve your API keys. For production access, complete the KYC verification process and request production access.

The sandbox environment is for testing and development. It uses test credentials and doesn't process real money. The production environment is for live transactions with real money. Both environments are completely separated - sandbox testing does not affect production data, and you can invite team members to sandbox without giving them production access.

Quotes are valid for 15 minutes. During this period, fees are locked in. After expiry, you must create a new quote as pricing may have changed. Each quote can only be used once when executing a collection or disbursement.

ZoPay currently supports MTN Mobile Money and Orange Money. Gateway availability and limits for your merchant account are managed by ZoPay—contact Help & Support if you need changes.

To verify your domain, add it in the Domain Settings section of your merchant dashboard. You'll receive a verification token. Add a DNS TXT record with the name '_zopay' and the token as the value at your domain registrar (where you bought the domain). Important: You must wait 15-30 minutes for DNS propagation before clicking 'Verify Domain'. If you're using Vercel, you cannot add DNS records to Vercel domains (*.vercel.app) - you need to use a custom domain and add the TXT record at your domain registrar, not in Vercel. Domain verification is required for production API access.

An idempotency key is a unique identifier you provide with each transaction request. It ensures that if you retry a request (due to network issues or timeouts), the same transaction won't be processed twice. Always generate a unique idempotency key for each transaction attempt. If you retry with the same key, ZoPay will return the original transaction result instead of creating a duplicate.

Webhooks allow you to receive real-time notifications about transaction events. After registering a webhook endpoint in your dashboard, ZoPay sends HTTP POST requests to your endpoint when events occur (like transaction completion or failure). Always verify the webhook signature in the X-Webhook-Signature header before processing webhook payloads for security.

If a transaction fails, you'll receive a webhook notification with the failure reason. You can also check the transaction status using the GET /api/v1/wallets/transactions/:id endpoint. Failed transactions are not charged to the customer. Common failure reasons include insufficient funds, incorrect phone number format, or gateway unavailability.

Fees consist of two components: gateway fees (charged by the mobile money provider like MTN or Orange) and platform fees (ZoPay service fee). When you create a quote, you'll receive the exact fee breakdown. Fees are locked in for 15 minutes with the quote. The total amount the customer pays includes the original amount plus all fees.

No, sandbox and production environments use completely separate API keys. Your sandbox API key will only work in the sandbox environment and should never be used in production. After completing KYC and requesting production access, you'll receive separate production API keys that should be kept secure and only used in production.

The default rate limit is 100 requests per minute per merchant. This is configurable based on your needs. If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a retry_after header indicating how many seconds to wait before retrying. Implement exponential backoff when handling rate limit responses.

Refunds can be processed through the ZoPay API. There are two methods: reversal (instant refund by reversing the original transaction) and manual refund (processed separately). To create a refund, use the refund endpoint with the original transaction ID and a reason. Refunds are subject to the same security and verification requirements as other transactions.