Troubleshooting
10.1 Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized / E006 |
Wrong or malformed Authorization header |
Rebuild Basic base64(username:password) from the Inbox values; check for stray spaces or newlines |
403 / E007 |
Sandbox not activated | Authentication tab → Request Sandbox Access → Save & Activate |
| No password after requesting access | The password goes to your portal Inbox | Inbox → Your sandbox credentials |
404 on every call |
Base path dropped (/sandbox/payment/v1 missing) or a trailing slash removed |
Log the full URL. It must be …/sandbox/payment/v1/transactions/amount/. |
400 / E001 |
A required field is missing or misspelled | Check charginginformation, chargeMetaData, terminalID spelling |
400 / E002 |
MSISDN format | Use 263XXXXXXXXX |
400 / E004 |
Amount has more than 2 decimals, or is zero or negative | Format as "10.00" |
400 / E005 |
clientCorrelator reused |
Generate a new one per charge and per refund |
| Charge accepted but no prompt on the phone | Number not whitelisted or verified | Test Numbers → add and OTP-verify it |
Status stays PENDING |
Customer hasn’t answered the prompt | Keep polling (sandbox resolves in 12–30 s). After your timeout, mark it unknown and re-check later. |
statusMessage says “Transaction Successful” but status is PENDING |
The documented example does this | Trust status only |
Status is null in your code |
Reading transactionStatus or transactionOperationStatus |
Read status first (8.7) |
Refund 409 / E009 |
Original isn’t SUCCESS, or was already refunded |
Look it up first |
Refund 422 / E012 |
Refund amount > original | Refund at most the original amount |
Refund rejected for tranType |
The portal’s pages disagree on REF vs MER |
Try the other value (4.5) |
| No sandbox SMS | Number not whitelisted | Whitelist and verify it |
| The portal’s cURL sample fails | It points at http://localhost:8080/... |
Use https://developers.ecocash.co.zw/sandbox/payment/v1 |
| No OTP when adding a test number | Not an EcoCash-registered number, or no signal | Use an active EcoCash number you have with you |
10.2 Debugging tips
- Log the resolved URL once at start-up. Most “404 everywhere” bugs are a dropped base path.
- Compare with the Playground. Send the same request from the API Playground and diff its cURL view against yours.
- Check the Request Console for the exact status and body the sandbox returned.
10.3 Getting help
| Channel | Contact | Response time |
|---|---|---|
| Developer support (integration, sandbox, API) | servicedelivery@ecocash.co.zw | 1 business day |
| Production access requests | servicedelivery@ecocash.co.zw | 2 business days |
| Developer hotline | +263 (0)782 380 583, Mon–Fri 08:00–17:00 CAT | — |
For problems with this guide, open an issue.
This page is generated from section 10 of the README in README.md. Spotted something wrong? Open an issue.