Sandbox testing
7.1 PIN test matrix
When a charge reaches the test phone, the PIN you enter decides the outcome:
| PIN | Scenario | HTTP | statusMessage |
|---|---|---|---|
0000 |
✅ Successful transaction | 200 OK | Transaction Successful |
1111 |
⚠️ Insufficient funds | 200 OK | Insufficient Balance |
2222 |
❌ Incorrect PIN | 200 OK | Transaction Failed - Invalid PIN |
9999 |
🚫 Limit exceeded | 200 OK | Transaction Limit Exceeded |
The customer enters these PINs. Your merchant PIN in the request body stays 1234.
The Error Reference maps PINs 1111 and 9999 to 422 errors (E010 and E013), so handle
both a 200 failure and a 422.
7.2 Test numbers
- Only whitelisted, OTP-verified numbers can be charged or receive sandbox SMS (step 2.5).
- Accepted formats:
263XXXXXXXXXor07XXXXXXXX, normalised automatically. Use263XXXXXXXXX. The portal’s examples also show a 9-digit form (773047653) that the normalisation note doesn’t mention.
7.3 Sandbox merchant values
The portal publishes two sets. Use the one on your Authentication tab (Set A) first.
| Field | Set A: Authentication tab, Playground, SDK samples | Set B: Documentation → Test Data |
|---|---|---|
merchantCode |
287164 |
001535 |
merchantPin |
1234 |
1234 |
merchantNumber |
778503033 |
788732685 |
terminalID |
TERM001 |
UAT00003 |
countryCode |
ZW |
ZW |
location |
Harare |
Harare |
superMerchantName |
EcoCash Sandbox |
ECOCASH |
merchantName |
Test Merchant |
UAT STORE 3 |
channel |
WEB |
POS |
7.4 SMS notifications
Every sandbox transaction, successful or failed, sends an SMS to the endUserId:
SANDBOX TEST: Your EcoCash payment of USD [amount] to [merchantName] (Ref: [referenceCode]) was SUCCESSFUL. This is a test transaction.
SANDBOX TEST: Your EcoCash payment of USD [amount] to [merchantName] (Ref: [referenceCode]) FAILED. Reason: [failureReason]. This is a test transaction.
[amount] comes from paymentAmount.charginginformation.amount, [merchantName] and
[referenceCode] from your request, and [failureReason] from the response statusMessage.
The number must be whitelisted to receive it.
7.5 Portal testing tools
| Tool | Where | What it does |
|---|---|---|
| API Playground | Product tab 2 | Send charge, lookup and refund requests from a form. Its cURL view shows the exact request. Its lookup can poll every 3 s. |
| Test Scenarios | Product tab 3 | Pre-built end-to-end flows. Full Happy Path: charge ZWG 75.00, poll until SUCCESS, verify. Initiate + Refund: charge ZWG 20.00, wait for SUCCESS, refund in full. Auth Failure Handling: wrong credentials and no header (expect 401 both times), then correct credentials. Validation & Edge Cases: missing amount (expect 400), then a valid payment. |
| Request Console | Product tab 5 | A live log of every sandbox call: method, path, status, latency, and full request and response bodies. |
7.6 Test checklist
Run every case and record the result. These are the cases EcoCash’s test script (Going live) asks for:
| ID | API | PIN | Expected result |
|---|---|---|---|
TC-001 |
Charge | 0000 |
Transaction Successful |
TC-002 |
Charge | 1111 |
Insufficient Balance |
TC-003 |
Charge | 2222 |
Transaction Failed - Invalid PIN |
TC-004 |
Charge | 9999 |
Transaction Limit Exceeded |
TC-005 |
Lookup | N/A | Transaction status returned |
TC-006 |
Refund / reversal | N/A | Refund processed successfully |
Also test your own failure handling: a wrong password (401), a reused clientCorrelator,
a refund above the original amount (422), and a network timeout during a charge (look it up,
don’t resend).
This page is generated from section 7 of the README in README.md. Spotted something wrong? Open an issue.