Testing Guide
Validate your EcobankPay integration before going live
Test Thoroughly Before Production
Overview
Testing your EcobankPay integration is a critical step before accepting real payments. This guide covers the testing process, including:
- Setting up your sandbox environment
- Test credentials and data
- Testing different payment methods
- Simulating successful and failed transactions
- Verification and validation processes
Sandbox Environment
EcobankPay provides a dedicated sandbox environment for testing your integration:
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://sandbox.ecobankpay.com/api/v1 | Testing and development |
| Production | https://api.ecobankpay.com/api/v1 | Live transactions |
Obtaining Sandbox Credentials
To access the sandbox environment:
- Contact EcobankPay support at
support@ecobankpay.comto request sandbox access - You will receive a Sandbox Merchant Key and Secret
- These credentials are different from your production credentials
- Use these sandbox credentials for all your testing
Important:
Never use production credentials in your development or testing environments, and never use sandbox credentials in production.
Test Data for Payment Methods
Mobile Money Test Data
Use these test phone numbers for simulating mobile money payments:
| Provider | Test Phone Numbers | Simulated Result |
|---|---|---|
| MTN Mobile Money | +233200000001 | Successful payment |
| MTN Mobile Money | +233200000002 | Failed payment (insufficient funds) |
| AirtelTigo Money | +233270000001 | Successful payment |
| AirtelTigo Money | +233270000002 | Failed payment (user cancelled) |
| Telecel Cash | +233500000001 | Successful payment |
| Telecel Cash | +233500000002 | Failed payment (timeout) |
Card Payment Test Data
Use these test cards for simulating card payments:
| Card Type | Card Number | Expiry | CVV | Result |
|---|---|---|---|---|
| VISA | 4111 1111 1111 1111 | Any future date | 123 | Successful |
| VISA (3DS) | 4242 4242 4242 4242 | Any future date | 123 | Successful with 3DS |
| MasterCard | 5555 5555 5555 4444 | Any future date | 123 | Successful |
| VISA (Declined) | 4000 0000 0000 0002 | Any future date | 123 | Declined |
| MasterCard (Declined) | 5105 1051 0510 5100 | Any future date | 123 | Declined |
3D Secure Testing:
For cards that trigger 3D Secure in the sandbox, use any value for the authentication code. In the sandbox, 3D Secure simulations always succeed when you provide any value.
Testing Scenarios
To thoroughly test your integration, implement these test scenarios:
1. Basic Payment Flows
- Successful payment with each supported payment method
- Failed payment with each supported payment method
- Cancelled payment (customer abandons payment)
- Expired transaction (payment not completed within time limit)
2. Notification Handling
- IPN (webhook) received and processed correctly
- Success URL redirect handling
- Cancelled URL redirect handling
- Status check API integration working properly
3. Error Scenarios
- Missing required parameters (e.g., merchant_key, invoice_id, total)
- Invalid secure_hash verification
- Duplicate invoice_id handling
- Network timeout and retry mechanisms
4. Edge Cases
- Very small transaction amounts (e.g., 0.01)
- Large transaction amounts (e.g., 9999.99)
- Special characters in description, invoice_id, etc.
- Multiple concurrent transactions
Simulating Specific Scenarios
You can simulate specific payment scenarios in the sandbox by using special values:
| Scenario | How to Simulate |
|---|---|
| Transaction Timeout | Use an amount of exactly 0.01 in the total field |
| Network Error | Use an amount of exactly 0.02 in the total field |
| Insufficient Funds | Use an amount of exactly 0.03 in the total field |
| Customer Cancellation | Use an amount of exactly 0.04 in the total field |
| Delayed Processing | Use an amount of exactly 0.05 in the total field |
Integration Verification Checklist
Before going live, verify that your integration meets these requirements:
| Category | Verification Item |
|---|---|
| Authentication | Secure hash implementation works correctly |
| Payment Flow | All supported payment methods can be initiated successfully |
| Notifications | IPN webhook endpoint receives and processes notifications |
| Status Checks | Payment status verification is implemented correctly |
| Error Handling | Application handles failed payments gracefully |
| Idempotency | System prevents duplicate order processing |
| UI/UX | User interface clearly communicates payment status |
| Security | Merchant credentials are stored securely (not in source code) |
| Environment | Code to switch between sandbox and production environments exists |
Going Live Checklist
When you're ready to move from sandbox to production:
- Complete all testing: Ensure all test scenarios pass in the sandbox environment
- Request production credentials: Contact EcobankPay support to obtain production credentials
- Update configuration: Change API endpoints and credentials to production values
- Implement logging: Ensure comprehensive logging is in place for troubleshooting
- Set up monitoring: Implement alerts for payment failures or abnormal patterns
- Perform a test transaction: Make a small real payment to verify the production setup
- Document the process: Create internal documentation for handling payment issues
Production Support:
Once live, EcobankPay's support team can be reached at support@ecobankpay.com or by phone at +233 XX XXX XXXX for urgent issues.