Known portal issues

The EcoCash portal’s Documentation tab, SDK samples and API Playground don’t always agree. This guide follows the safest reading in each case. Here’s what differs, so you aren’t surprised.

11.1 Differences between portal pages

Topic	Documentation tab	Playground / SDK samples	This guide
amount type	JSON number (2), declared Decimal	String ("30.00", "5.00")	String with 2 decimals; confirm in your first run
Refund tranType	REF (refund) / REV (reversal)	MER, plus a top-level currencyCode	REF/REV, configurable; confirm in your first run
Merchant values	001535 / 788732685 / UAT00003 / POS	287164 / 778503033 / TERM001 / WEB	Your Authentication tab’s set
Status field	status	transactionStatus (Java/PHP/JS/C#), transactionOperationStatus (Python)	Read status, fall back to the others
Refund reference field	Listed in the field table, missing from the example body	Required in the Playground and in every SDK sample	Always send originalEcocashReference
Charge reference field	Response shows transactionId	The Playground reads ecocashReference	Use ecocashReference if present, else transactionId
Test-script download	“Download Test Script” (blank template)	Production tab: “Download Completed Test Script” (generated from captured evidence)	Follow the Production tab

11.2 Contradictions within the Documentation tab

Topic	The contradiction	What to do
Reusing a clientCorrelator	E005 says it’s an error; Test Data says it returns the existing transaction	Never reuse one
PIN 1111 / 9999	Test Data: HTTP 200; Error Reference: 422 (E010 / E013)	Handle both
Charge example	status: PENDING with statusMessage: "Transaction Successful"	Trust status
Lookup path	Overview: {correlator}; API Reference: {clientCorrelator}	Same value, your clientCorrelator
SMS prefix	Described as “ECOCASH SANDBOX”; the templates say SANDBOX TEST:	Expect SANDBOX TEST:
SMS currency	Templates hard-code USD	Don’t expect ZWG in the SMS text
HTTP status tables	Each endpoint lists only some codes; 403 and 503 appear in none	Handle every code on every endpoint
Invalid-PIN error	PIN 2222 has no Exxx code	Detect it from statusMessage

11.3 Open questions

These aren’t published anywhere on the portal. Ask EcoCash support before production:

1. Which amount format and which refund tranType does the backend accept?
2. Which merchant set is valid in the sandbox, and what are your production values?
3. What does a notifyUrl callback contain, and what are its signature header, secret and retry policy?
4. What is the full list of status values, and which statusCode goes with each Exxx error?
5. What response does the rate limit (500/min) return: 429, and is Retry-After sent?
6. Is ZWG accepted on every endpoint?

---

This page is generated from section 11 of the README in README.md. Spotted something wrong? Open an issue.