Troubleshooting

This guide helps you troubleshoot common issues when integrating with the Zikopay API.

Authentication Issues

Invalid API Key

Symptom: You receive a 401 Unauthorized response with the message "Invalid API Key"

Solution:

• Verify you're using the correct API key and secret
• Check for whitespace or extra characters in your key
• Ensure you're using the right key for the environment (test vs. production)

API Key Permissions

Symptom: You receive a 403 Forbidden response when calling certain endpoints

Solution:

• Check if your API key has the necessary permissions
• Request additional scopes for your API key if needed

Transaction Issues

Failed Transactions

Symptom: Transactions are failing consistently

Solution:

• Check the error message in the response for specific details
• Verify customer information is correct (phone number format, etc.)
• Ensure you're using a supported operator for the customer's region
• Confirm the customer has sufficient funds

Pending Transactions

Symptom: Transactions are stuck in "pending" status

Solution:

• Check if the customer completed the payment on their device
• Verify your webhook URL is accessible and responding with 200 OK
• Wait for the standard processing time (up to 15 minutes for mobile money)
• Use the transaction status API to check for updates

Webhook Issues

Missing Webhooks

Symptom: You're not receiving webhooks for transaction updates

Solution:

• Verify your webhook URL is publicly accessible
• Check server logs to confirm requests are reaching your server
• Ensure your server responds with a 200 OK status code
• Verify firewall settings allow incoming requests from Zikopay IPs

Duplicate Webhooks

Symptom: You receive the same webhook multiple times

Solution:

• Implement idempotent processing using the transaction reference
• Return 200 OK responses promptly to acknowledge receipt

Mobile Money Issues

Operator Not Available

Symptom: You get an error that the selected operator is not available

Solution:

• Verify the operator code is correct (e.g., mtn_cm, orange_cm)
• Check if the operator is supported in the customer's country
• Confirm your merchant account is enabled for this operator

USSD Prompt Not Received

Symptom: Customer reports not receiving the USSD prompt to complete payment

Solution:

• Verify the phone number format includes country code (e.g., 237xxxxxxxxx)
• Check if the customer has an active account with the operator
• Suggest the customer check their network connection

Common Error Codes

Error Code	Description	Solution
invalid_request	Missing or invalid parameters	Check request parameters against API docs
insufficient_funds	Wallet balance too low for payout	Add funds to your merchant wallet
operator_unavailable	Selected payment operator is unavailable	Try an alternative operator or try again later
invalid_phone	Phone number format is invalid	Check country code and number format
transaction_expired	Payment request has expired	Create a new transaction

Contact Support

If you continue to experience issues after trying these troubleshooting steps, please contact our support team:

• Email: support@zikopay.com
• Include your merchant ID and transaction references
• Provide detailed error messages and steps to reproduce the issue