Documentation tab (verbatim)

Source of truth: EcoCash Developer Portal → Products → EcoCash Instant Payment → Documentation tab — and nothing else Product: EcoCash Instant Payment — Online Payment Gateway (Full Sandbox Simulation) Auth: HTTP Basic Auth (per the Documentation tab’s Quick Facts) Document revision: 1.5 · last verified against the live Documentation tab on 21 September 2026

Scope. This document reflects only the Documentation tab’s seven sub-sections: Overview, Authentication, API Reference, Error Reference, Test Data, SMS Notifications and Test Script. It takes no content from any other tab or page of the portal, and it is not reconciled against them. The SDKs & Codegen tab is covered separately, on the same basis, in ECOCASH-EIP-SDK-REFERENCE.md.

---

Table of Contents

1. Overview
2. Authentication
3. API Reference
   • API 1 — Charge Request
   • API 2 — Transaction Lookup
   • API 3 — Refund / Reversal
4. Error Reference
5. Test Data
6. SMS Notifications
7. Test Script (Certification)
8. End-to-End Integration Walkthrough
9. Verification Notes & Documented Inconsistencies
10. Appendix A — Source Verification Log

---

1. Overview

EcoCash Online Payments API

Accept instant payments from EcoCash wallets with real-time transaction processing. The product supports merchant charge requests, transaction lookup, and refunds/reversals, with webhook notification callbacks.

Sandbox Base URL

https://developers.ecocash.co.zw/sandbox/payment/v1

Sandbox environment — all transactions are simulated and no real money is moved.

Quick Facts

The portal’s Quick Facts card contains exactly these five entries:

Item	Value
Auth	HTTP Basic Auth
Protocol	HTTPS / REST
Format	application/json
tranType values	MER · REF · REV
Currencies	USD, ZWG

Endpoints Summary

Method	Path	Name
POST	/transactions/amount/	API 1 — Charge Request
GET	/{endUserId}/transactions/amount/{correlator}	API 2 — Transaction Lookup
POST	/transactions/refund/	API 3 — Refund / Reversal

In the Overview the lookup path placeholder is shown as {correlator}; in the API Reference (endpoint header, Path Parameters table and cURL example) it is shown as {clientCorrelator}. Both refer to the same value: the clientCorrelator from the original Charge Request. See §9.

notifyUrl Callbacks

Provide a notifyUrl in your charge or refund request to receive real-time event callbacks for payment lifecycle changes.

An SMS is also sent to the endUserId on every transaction outcome — see SMS Notifications.

---

2. Authentication

All API requests use HTTP Basic Authentication. Credentials are issued per developer after requesting sandbox access — include the Authorization header on every call.

How to get your credentials

1. Go to the Authentication tab in the EIP API Playground and click “Request Sandbox Access”.
2. Your username is returned immediately. Your password is dispatched to your developer inbox.
3. Enter both in the credential form and click “Save & Activate” to enable the playground.

Using your credentials

1. Combine your username and password as username:password
2. Base64-encode the combined string
3. Prefix with "Basic " and set as the Authorization header on every request

Credentials are stored in localStorage by the portal and injected automatically into every Playground request. Never commit them to source control.

cURL Example

curl -X POST 'https://developers.ecocash.co.zw/sandbox/payment/v1/transactions/amount/' \
  -H 'Authorization: Basic <your-base64-credentials>' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Java / Spring Boot

String credentials = username + ":" + password;
String encoded = Base64.getEncoder()
        .encodeToString(credentials.getBytes(StandardCharsets.UTF_8));

HttpHeaders headers = new HttpHeaders();
headers.set("Authorization", "Basic " + encoded);
headers.setContentType(MediaType.APPLICATION_JSON);

The portal labels this block’s code fence json; it is Java. Rendered here as java — one of the deliberate departures listed in Appendix A.3. See A.3.

---

3. API Reference

Three core APIs — Charge Request, Transaction Lookup, and Refund/Reversal.

tranType values: MER — merchant charge · REF — refund · REV — reversal

Scope note: each endpoint’s “Key Request Fields” table is a curated subset, not a complete schema. API 1 documents 11 fields while its body carries 16 top-level keys (22 field names including nested); API 3 documents 4. Always treat the Request Body sample as the authoritative shape.

---

API 1 — Charge Request

POST /transactions/amount/

Initiates a payment charge request from a merchant to a customer’s EcoCash wallet. The customer receives a USSD PIN prompt to confirm. Use the PIN Test Matrix (see Test Data) to simulate different outcomes in the sandbox.

Key Request Fields

Field	Type	Description
clientCorrelator	String	Unique merchant-generated identifier for this transaction
referenceCode	String	Merchant’s own reference code for the transaction
endUserId	String	Customer’s EcoCash MSISDN (mobile number)
tranType	String	Transaction type — use MER for merchant-initiated
amount	Decimal	Charge amount in the specified currency
currency	String	ISO 4217 currency code, e.g. USD
merchantCode	String	EcoCash-assigned merchant identifier
merchantPin	String	Merchant’s security PIN
merchantNumber	String	Merchant’s registered MSISDN
terminalID	String	POS terminal identifier
notifyUrl	String	Callback URL for payment notifications

amount and currency are not top-level keys — they are carried inside paymentAmount.charginginformation in the wire payload (see body below).

Request Body

{
  "clientCorrelator": "1774252612",
  "notifyUrl": "",
  "referenceCode": "TEST_1774252612",
  "tranType": "MER",
  "endUserId": "773047653",
  "remarks": "EcoCash Sandbox",
  "transactionOperationStatus": "Charged",
  "paymentAmount": {
    "charginginformation": {
      "amount": 2,
      "currency": "USD",
      "description": "UAT STORE 3"
    },
    "chargeMetaData": {
      "channel": "POS"
    }
  },
  "merchantCode": "001535",
  "merchantPin": "1234",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}

HTTP Status Codes

Code	Meaning
200	Request accepted — check status field for outcome
400	Invalid request parameters
401	Unauthorized — check Basic Auth credentials
422	Business rule violation (barred number, etc.)
500	Internal server error

Example Response

{
  "transactionId": "MP230422.1145.T0123456",
  "clientCorrelator": "1774252612",
  "status": "PENDING",
  "statusCode": "200",
  "statusMessage": "Transaction Successful",
  "amount": 2,
  "currency": "USD",
  "endUserId": "773047653",
  "merchantCode": "001535",
  "timestamp": "2024-04-22T11:45:30Z"
}

Example Request

curl -X POST 'https://developers.ecocash.co.zw/sandbox/payment/v1/transactions/amount/' \
  -H 'Authorization: Basic <your-base64-credentials>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientCorrelator": "1774252612",
  "notifyUrl": "",
  "referenceCode": "TEST_1774252612",
  "tranType": "MER",
  "endUserId": "773047653",
  "remarks": "EcoCash Sandbox",
  "transactionOperationStatus": "Charged",
  "paymentAmount": {
    "charginginformation": {
      "amount": 2,
      "currency": "USD",
      "description": "UAT STORE 3"
    },
    "chargeMetaData": {
      "channel": "POS"
    }
  },
  "merchantCode": "001535",
  "merchantPin": "1234",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}'

---

API 2 — Transaction Lookup

GET /{endUserId}/transactions/amount/{clientCorrelator}

Retrieves the status and details of a transaction using the customer mobile number and clientCorrelator. Use this to poll for the final outcome after a charge request, or when no notifyUrl webhook is configured.

Path Parameters

Parameter	Type	Description
endUserId	string	Customer MSISDN used in the original Charge Request
clientCorrelator	string	Unique correlator from the original Charge Request

HTTP Status Codes

Code	Meaning
200	Transaction details returned
401	Unauthorized access
404	Transaction not found for the given endUserId + correlator

Example Response

{
  "transactionId": "MP230422.1145.T0123456",
  "clientCorrelator": "1774252612",
  "status": "SUCCESS",
  "statusCode": "200",
  "endUserId": "773047653",
  "amount": 2,
  "currency": "USD",
  "merchantCode": "001535",
  "merchantName": "UAT STORE 3",
  "referenceCode": "TEST_1774252612",
  "timestamp": "2024-04-22T11:45:30Z",
  "description": "UAT STORE 3"
}

Example Request

curl -X GET 'https://developers.ecocash.co.zw/sandbox/payment/v1/{endUserId}/transactions/amount/{clientCorrelator}' \
  -H 'Authorization: Basic <your-base64-credentials>'

---

API 3 — Refund / Reversal

POST /transactions/refund/

Initiates a reversal or refund for a previously completed EcoCash Online Payment. Use tranType REF for a customer refund or REV for a merchant reversal. Requires the original EcoCash transaction reference.

Key Request Fields

Field	Type	Description
tranType	String	REF for Refund, REV for Reversal
originalEcocashReference	String	EcoCash transaction reference from the original charge response
clientCorrelator	String	New unique correlator for this refund transaction
amount	Decimal	Amount to refund — must not exceed original charge amount

Request Body

{
  "clientCorrelator": "1774252613",
  "notifyUrl": "",
  "referenceCode": "TEST_1774252613",
  "tranType": "REF",
  "endUserId": "773047653",
  "remarks": "EcoCash Sandbox",
  "transactionOperationStatus": "Charged",
  "paymentAmount": {
    "charginginformation": {
      "amount": 2,
      "currency": "USD",
      "description": "UAT STORE 3"
    },
    "chargeMetaData": {
      "channel": "POS"
    }
  },
  "merchantCode": "001535",
  "merchantPin": "1234",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}

The portal’s documented refund body sample does not itself include originalEcocashReference, although the field table lists it as a key request field and the description states the original reference is required. See §9.

HTTP Status Codes

Code	Meaning
200	Refund/reversal accepted
400	Invalid request
404	Original transaction not found
409	Transaction not eligible for refund/reversal
422	Refund amount exceeds original payment

Example Response

{
  "transactionId": "RF230422.1200.R0123456",
  "clientCorrelator": "1774252613",
  "status": "SUCCESS",
  "statusCode": "200",
  "statusMessage": "Refund processed successfully",
  "originalReference": "MP230422.1145.T0123456",
  "amount": 2,
  "currency": "USD",
  "timestamp": "2024-04-22T12:00:15Z"
}

Example Request

curl -X POST 'https://developers.ecocash.co.zw/sandbox/payment/v1/transactions/refund/' \
  -H 'Authorization: Basic <your-base64-credentials>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientCorrelator": "1774252613",
  "notifyUrl": "",
  "referenceCode": "TEST_1774252613",
  "tranType": "REF",
  "endUserId": "773047653",
  "remarks": "EcoCash Sandbox",
  "transactionOperationStatus": "Charged",
  "paymentAmount": {
    "charginginformation": {
      "amount": 2,
      "currency": "USD",
      "description": "UAT STORE 3"
    },
    "chargeMetaData": {
      "channel": "POS"
    }
  },
  "merchantCode": "001535",
  "merchantPin": "1234",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}'

---

4. Error Reference

All errors return a JSON body with statusCode and statusMessage fields. Error messages must be developer-friendly and include a resolution hint.

Code	HTTP	Title	Description
E001	400	Missing required field	A required request field is absent or empty.
E002	400	Invalid MSISDN format	endUserId must be a valid Zimbabwe MSISDN, e.g. 773047653.
E003	400	Invalid currency	currency must be "USD" or "ZWG".
E004	400	Invalid amount	Amount must be a positive number with at most 2 decimal places.
E005	400	Duplicate correlator	clientCorrelator already used. Each transaction must have a unique value.
E006	401	Invalid credentials	Authorization header is missing, malformed, or username/password is wrong.
E007	403	Sandbox not enabled	Request Sandbox Access on the Authentication tab before making API calls.
E008	404	Transaction not found	No transaction exists for the given endUserId + clientCorrelator combination.
E009	409	Refund not eligible	Transaction is in a state that does not allow refund/reversal (e.g. already refunded).
E010	422	Insufficient funds	Customer wallet balance is too low. Simulate via PIN 1111.
E011	422	Barred MSISDN	The customer MSISDN is barred from making EcoCash transactions.
E012	422	Refund exceeds original	Refund amount is greater than the original transaction amount.
E013	422	Limit exceeded	Transaction limit exceeded for this wallet. Simulate via PIN 9999.
E014	500	Internal server error	Unexpected server error. Retry with exponential backoff; contact support if persistent.
E015	503	Service unavailable	Sandbox is under maintenance. Retry after the maintenance window.

---

5. Test Data

Sandbox credentials, PIN simulation matrix, and how to whitelist your own test MSISDNs.

Sandbox PIN Test Matrix

When a Charge Request is sent, EcoCash pushes a USSD PIN prompt to the customer’s MSISDN. In the sandbox the developer uses one of these pre-defined PINs to simulate a transaction outcome. All scenarios return HTTP 200 — the outcome is indicated by the statusMessage field in the response body.

PIN	Scenario	Expected HTTP Status	Expected Response Message
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 subscriber enters this PIN at the USSD prompt after a charge request is sent. Your merchant credentials (merchantPin: 1234) remain fixed regardless of which test PIN the customer uses.

Test Numbers (endUserId)

Any developer can whitelist their own Zimbabwe MSISDN and use it as endUserId in sandbox requests. Go to Test Numbers in the sidebar to register and OTP-verify a number.

1. 📱 Add your number — Enter any valid Zimbabwe MSISDN on the Test Numbers page.
2. 🔐 Verify via OTP — EcoCash sends a one-time code to the number for identity confirmation.
3. ✅ Use in sandbox calls — Pass the verified number as endUserId in your charge requests, then use the PIN matrix above to drive the outcome.

MSISDN format accepted: 263XXXXXXXXX or 07XXXXXXXX — normalised automatically.

Sandbox Merchant Credentials

Field	Value
merchantCode	001535
merchantPin	1234
merchantNumber	788732685
terminalID	UAT00003
countryCode	ZW
superMerchantName	ECOCASH
merchantName	UAT STORE 3
channel	POS

clientCorrelator rules

• Must be unique per transaction
• Used to look up the transaction after creation
• Reusing a correlator returns the existing transaction

---

6. SMS Notifications

Upon completion of any sandbox transaction — successful or failed — the system automatically sends an SMS to the endUserId (customer MSISDN) specified in the request.

What the SMS contains

Element	Detail
💰 Amount	Transaction amount and currency
🏪 Merchant Name	Name of the merchant as sent in the request
🔖 Reference Code	The referenceCode from the charge request
🕐 Timestamp	Date and time of the transaction attempt
🏷️ Sandbox Label	"ECOCASH SANDBOX" prefix — distinguishes from production messages

SMS delivery in the sandbox environment is handled by EcoCash’s existing SMS gateway. The MSISDN must be whitelisted via Test Numbers before it can receive sandbox SMS notifications.

Success Template

SANDBOX TEST: Your EcoCash payment of USD [amount] to [merchantName] (Ref: [referenceCode]) was SUCCESSFUL. This is a test transaction.

Failed Template

SANDBOX TEST: Your EcoCash payment of USD [amount] to [merchantName] (Ref: [referenceCode]) FAILED. Reason: [failureReason]. This is a test transaction.

Template Variables

Variable	Source Field
[amount]	paymentAmount.charginginformation.amount
[merchantName]	merchantName
[referenceCode]	referenceCode
[failureReason]	Response statusMessage (failed only)

---

7. Test Script (Certification)

A standardised test script (Excel format) is available from the portal. Developers fill it in as they execute each test case — it is required as an attachment when submitting a production access request.

Why it matters

1. Certification artefact — The completed test script is the primary evidence that you have validated your integration against all four PIN scenarios.
2. Required for go-live — You cannot submit a production access request without attaching a signed-off test script.
3. Admin review — The EcoCash team reviews the script alongside your merchant MSISDN before issuing production credentials.

Script Columns

Columns marked developer fills must be completed as you run each test case.

Column	Description
Test Case ID	Sequential identifier for each test case (e.g. TC-001)
API Tested	Charge Request / Transaction Lookup / Refund
Test PIN Used	0000 / 1111 / 2222 / 9999 — from the PIN Matrix
Merchant Reference	The referenceCode used in the request
Expected Result	What the BRD says should happen for this PIN
Actual Result	What actually came back — developer fills this in
Status	Pass or Fail — developer fills this in
Comments	Any observations or deviations — developer fills this in

Pre-populated Test Cases

The downloaded template includes one row per PIN scenario plus lookup and refund.

ID	API	PIN	Expected Result
TC-001	Charge Request	0000	Transaction Successful
TC-002	Charge Request	1111	Insufficient Balance
TC-003	Charge Request	2222	Transaction Failed - Invalid PIN
TC-004	Charge Request	9999	Transaction Limit Exceeded
TC-005	Transaction Lookup	N/A	Transaction status returned
TC-006	Refund / Reversal	N/A	Refund processed successfully

How to get the template: the Download Test Script button is available on the Production tab. Complete all test cases, save, and upload the file when submitting your production access request.

---

8. End-to-End Integration Walkthrough

This walkthrough draws only on §1–§7 (the Documentation tab). Each step names the section it comes from.

Recommended implementation order

1. Request sandbox access (§2). Go to the Authentication tab in the EIP API Playground and click Request Sandbox Access. Your username is returned immediately; your password is dispatched to your developer inbox. Enter both and click Save & Activate.
2. Store the credentials outside source control (§2): environment variables or a secret manager. Never commit them.
3. Build the Basic Auth header (§2): Basic base64(username:password). Send it on every request, together with Content-Type: application/json (§1 Quick Facts: format application/json).
4. Whitelist a test MSISDN (§5). Go to Test Numbers in the sidebar, add a Zimbabwe number and verify it by OTP. The number must be whitelisted before it can receive sandbox SMS (§6).
5. Call API 1, POST /transactions/amount/ (§3), with:
   • a new unique clientCorrelator
   • the whitelisted number as endUserId
   • tranType: "MER"
   • the sandbox merchant credentials from §5.

   The documented example response is HTTP 200 with status: "PENDING".

6. Have the subscriber enter a PIN from the §5 matrix (0000, 1111, 2222 or 9999) at the USSD prompt. The merchant PIN (1234) stays fixed.
7. Resolve the final state (§1, §3). Use your notifyUrl callback, or poll API 2: GET /{endUserId}/transactions/amount/{clientCorrelator}.
8. Confirm the SMS reached the endUserId (§6). The templates begin SANDBOX TEST:.
9. Exercise API 3, POST /transactions/refund/ (§3), with:
   • tranType: "REF" (refund) or "REV" (reversal)
   • a new unique clientCorrelator
   • originalEcocashReference from the original charge
   • an amount no greater than the original charge.
10. Record every run in the test script, TC-001 … TC-006 (§7). Download the template from the Production tab, as §7 describes. Complete it and upload it with your production access request.

Error-handling rules

• Treat HTTP 200 as “accepted”, not “succeeded” (§5). All PIN scenarios return 200 OK, and the outcome is in the response body (statusMessage; the endpoint examples also carry status). But see §9 row 17: the Error Reference maps PINs 1111 and 9999 to 422 codes.
• Never reuse a clientCorrelator. E005 treats reuse as an error, although Test Data describes different behaviour (§9 row 9).
• Retry E014 (500) with exponential backoff, and E015 (503) once the maintenance window has passed (§4).
• Do not retry 400 / 401 / 403 / 404 / 409 / 422. These are deterministic and will fail the same way on replay. Fix the request, credentials or business state first.
• Log statusCode and statusMessage verbatim. The Error Reference says every error body carries both, and that messages include a resolution hint (§4).

Security and operational notes

• Credentials are issued per developer (§2). Don’t share them across environments.
• The merchantPin travels inside the request body (§3). Enforce TLS (§1: HTTPS / REST) and redact request bodies in application logs.
• Every documented example sends notifyUrl as an empty string. The Documentation tab does not describe the callback payload, signing, retries or delivery guarantees. Treat callbacks as hints and confirm the outcome via API 2.
• Sandbox transactions are simulated and move no real money (§1). SMS delivery goes through EcoCash’s existing SMS gateway and reaches only whitelisted numbers (§6).

---

9. Verification Notes & Documented Inconsistencies

The Documentation tab contains internal contradictions and naming irregularities. Sections 1–7 reproduce the tab verbatim rather than silently normalising it; each irregularity is catalogued here instead. Every row compares one part of the Documentation tab with another part of it. No other tab is consulted. Where a row says “reproduce as-is”, copy the tab’s exact spelling into your code.

#	Area	What the Documentation tab says	Issue	Guidance
1	Charge & refund body	charginginformation	All-lowercase inside an otherwise camelCase schema. Appears in the API 1 body, API 1 cURL, API 3 body, API 3 cURL and the SMS template-variable table.	Reproduce as-is. Do not “fix” to chargingInformation.
2	Charge & refund body	chargeMetaData	Capital D in “MetaData”; conventional camelCase would be chargeMetadata.	Reproduce as-is.
3	Charge & refund body	terminalID	Capital ID, whereas endUserId and clientCorrelator use lowercase d.	Reproduce as-is.
4	Endpoint paths	POST /transactions/amount/ and POST /transactions/refund/ end with a slash; GET /{endUserId}/transactions/amount/{clientCorrelator} does not.	Inconsistent trailing-slash convention.	Preserve the slashes exactly as printed. Some gateways treat /x and /x/ as distinct routes.
5	API 2 path parameter	Overview → Endpoints Summary prints /{endUserId}/transactions/amount/{correlator}. The API Reference (endpoint header, Path Parameters table, cURL) prints {clientCorrelator}.	The same path parameter has two names.	Use clientCorrelator. It matches the request-body field and the Path Parameters table.
6	API 3 required field	The Key Request Fields table lists originalEcocashReference (“EcoCash transaction reference from the original charge response”). The description says the original reference is required.	It is absent from API 3’s example request body and cURL. API 3’s example response returns the reference as originalReference. The API 1 example response has no field of either name (it carries transactionId).	Send originalEcocashReference per the field table and description. Read originalReference from the refund response.
7	API 1 vs API 3 bodies	Both example bodies contain the same 16 top-level keys (22 field names counting the nested charginginformation and chargeMetaData members).	Only three values differ: clientCorrelator (1774252612 → 1774252613), referenceCode (TEST_1774252612 → TEST_1774252613) and tranType (MER → REF). The refund body carries no link to the original transaction, and still sends transactionOperationStatus: "Charged".	See row 6: the refund example is incomplete.
8	MSISDN format	773047653 (all API examples and error E002) versus 263XXXXXXXXX or 07XXXXXXXX, “normalised automatically” (Test Data).	The 9-digit form used in every example is not among the formats the normalisation note lists.	Prefer 263XXXXXXXXX, which Test Data explicitly accepts. Don’t assume the 9-digit form is normalised.
9	Duplicate correlator	Error Reference E005: “clientCorrelator already used. Each transaction must have a unique value.” Test Data → clientCorrelator rules: “Reusing a correlator returns the existing transaction.”	Direct contradiction. One says reuse is a 400 error; the other says it is an idempotent lookup.	Always generate a unique correlator. Do not rely on idempotent replay.
10	SMS prefix	What the SMS contains → Sandbox Label describes an "ECOCASH SANDBOX" prefix. Both message templates begin SANDBOX TEST:.	The described prefix is not the one in the templates.	Match on SANDBOX TEST:, the literal text in the templates.
11	HTTP status tables	API 1 lists 200, 400, 401, 422, 500. API 2 lists 200, 401, 404. API 3 lists 200, 400, 404, 409, 422.	No endpoint table is complete relative to the Error Reference. 403 (E007) and 503 (E015) appear in no endpoint table.	Handle the full E001–E015 range on every endpoint.
12	API 1 example response	"status": "PENDING" together with "statusMessage": "Transaction Successful".	A pending transaction cannot also be successful.	The charge is asynchronous. Trust status, then re-read it from API 2 or the callback.
13	Error identifiers	The Error Reference uses codes E001–E015 with columns Code / HTTP / Title / Description. Example response bodies carry statusCode (e.g. the string "200") and statusMessage.	No mapping is given between Exxx codes and statusCode values, and statusCode is a string even for success.	Parse statusCode as a string. Map Exxx codes by statusMessage text until a mapping is published.
14	PIN 2222	The PIN matrix defines 2222 → “Transaction Failed - Invalid PIN”.	No Exxx code covers an invalid customer PIN (E010 = funds, E011 = barred, E013 = limit).	Detect this case from statusMessage only.
15	Authentication code block	The block headed “Java / Spring Boot” is labelled json but contains Java.	Markup defect.	Labelled java in this document (§2; Appendix A.3).
16	Currency coverage	Quick Facts and E003 allow USD and ZWG. API 1’s field table says “ISO 4217 currency code, e.g. USD”. Every example uses USD. The SMS templates hard-code USD [amount].	ZWG is never shown in an example, and the SMS templates don’t use the request currency.	Both currencies are valid per E003. Don’t expect the SMS text to reflect ZWG.
17	PIN outcomes vs error codes	Test Data: “All scenarios return HTTP 200”, including 1111 (Insufficient Balance) and 9999 (Transaction Limit Exceeded). Error Reference: E010 Insufficient funds is 422 (“Simulate via PIN 1111”) and E013 Limit exceeded is 422 (“Simulate via PIN 9999”).	The same simulated outcomes are documented with two different HTTP statuses.	Handle both: a 200 whose statusMessage carries the failure, and a 422 with E010 / E013.

Canonical field-name checklist

Copy these spellings exactly, as the Documentation tab prints them.

Correct spelling	Common mis-spelling to avoid
charginginformation	chargingInformation, charginginfo
chargeMetaData	chargeMetadata, chargemetadata
terminalID	terminalId, terminalid
endUserId	endUserID, enduserId
clientCorrelator	correlator, clientCorrelatorId
referenceCode	reference, refCode
merchantPin	merchantPIN, merchantPassword
notifyUrl	notifyURL, callbackUrl
superMerchantName	superMerchant, superMerchantname
transactionOperationStatus (request)	transactionOperationsStatus
originalEcocashReference (request)	originalReference (that is the response name)
status (response)	transactionOperationStatus (that is a request field, sent as "Charged")

---

Appendix A — Source Verification Log

A.1 Capture method and scope

All content in sections 1–7 was captured directly from https://developers.ecocash.co.zw/portal by opening the Documentation tab and each of its seven sub-sections in turn: Overview, Authentication, API Reference, Error Reference, Test Data, SMS Notifications, Test Script.

On the API Reference page, API 1 — Charge Request is expanded by default; API 2 — Transaction Lookup and API 3 — Refund / Reversal are collapsed and were each clicked open before capture.

The Documentation tab is this document’s only source of truth. Nothing in it is drawn from, or reconciled against, any other tab or page of the portal. Where the Documentation tab mentions another part of the portal (for example the Authentication tab, Test Numbers, or the Production tab), those mentions are reproduced as written and are not expanded on.

A.2 Figures actually counted

Claim	Verified value
Documentation sub-sections	7
Core endpoints	3
Error codes	15 (E001–E015, contiguous)
PIN matrix rows	4 (0000, 1111, 2222, 9999)
Pre-populated test cases	6 (TC-001–TC-006)
Test-script columns	8, of which 3 are marked “developer fills” (Actual Result, Status, Comments)
Overview Quick Facts entries	5 (Auth, Protocol, Format, tranType values, Currencies)
API 1 Key Request Fields rows	11
API 3 Key Request Fields rows	4
API 2 Path Parameters rows	2
Charge / refund request body	16 top-level keys; 22 distinct field names including the nested members of charginginformation and chargeMetaData
SMS template variables	4
Sandbox credential fields on Test Data	8 (merchantCode, merchantPin, merchantNumber, terminalID, countryCode, superMerchantName, merchantName, channel)
Per-endpoint HTTP status tables	3 (one each for API 1, API 2, API 3)

A.3 Deliberate departures from portal markup

Each item below is a knowing deviation, made for correctness or readability. Nothing else was altered.

1. The Authentication sub-section’s Java snippet is tagged json on the portal; it is tagged java here (§9 row 15).
2. Portal code blocks render without syntax-highlight hints in extracted text; appropriate fence labels (json, bash, http, java) have been applied here.
3. Emoji used decoratively in the portal’s PIN matrix and SMS feature cards is retained where it carries meaning and dropped where it is purely ornamental.
4. Portal tables that render as loose label/value pairs (Quick Facts, Sandbox Merchant Credentials) are rendered as proper two-column markdown tables.
5. Line wrapping has been introduced in long prose paragraphs. No wording was changed.
6. Section numbering (§1–§9) is this document’s own; the portal uses named sub-sections only.
7. Cross-reference notes inside §1–§7 (the > blockquotes pointing to §9 or Appendix A) are this document’s own commentary, not portal text.

A.4 Open questions for EcoCash support

Each of these comes from the Documentation tab alone.

1. Must originalEcocashReference be sent on refunds, given its absence from the example body? (§9 row 6)
2. Which field of the charge response holds the value for originalEcocashReference? The API 1 example response shows only transactionId. (§9 row 6)
3. Is the refund response field originalReference the same value as the request’s originalEcocashReference? (§9 row 6)
4. Does reusing a clientCorrelator raise E005 or return the existing transaction? (§9 row 9)
5. What statusCode value accompanies each Exxx error? (§9 row 13)
6. Which Exxx code, if any, corresponds to PIN 2222 / invalid customer PIN? (§9 row 14)
7. Do PINs 1111 and 9999 return HTTP 200 (Test Data) or 422 with E010 / E013 (Error Reference)? (§9 row 17)
8. What is the full set of status values? The Documentation shows only PENDING and SUCCESS.
9. What does a notifyUrl callback contain, and is it signed or retried? (§8)
10. Is the 9-digit MSISDN form (773047653) accepted, given the normalisation note lists only 263XXXXXXXXX and 07XXXXXXXX? (§9 row 8)
11. Is ZWG accepted on every endpoint, and does the SMS text then show ZWG? (§9 row 16)

A.5 Verification method

Content was captured, then re-verified on later passes. The latest pass (21 September 2026) re-opened all seven Documentation sub-sections, with the three API Reference endpoints expanded, and confirmed that §1–§7 match the live tab word for word, and that each figure in A.2 and each row in §9 holds.

A.6 Revision history

• 1.5 (21 September 2026):
  • Scope restricted to the Documentation tab as the only source of truth.
  • Removed everything taken from outside the tab: product-header metadata (rate limit, version/status), comparisons with the SDKs & Codegen tab, and material from the API Playground, product Authentication tab, Test Scenarios, Production, Request Console, Test Numbers page, Help & Support, Terms of Use and portal source code (the former §10).
  • §8 rewritten from §1–§7 only.
  • §9 reduced to Documentation-internal inconsistencies and renumbered; row 17 (PIN outcomes vs E010 / E013) added.
  • A.4 rewritten from Documentation-only evidence.
• 1.4: added cross-tab material (withdrawn in 1.5).
• 1.3: previous baseline.

---

Compiled solely from the EcoCash Developer Portal — EcoCash Instant Payment (Sandbox Simulation), https://developers.ecocash.co.zw/portal, Documentation tab. Sections 1–7 reproduce that tab verbatim; deliberate deviations are listed in Appendix A.3 and the tab’s internal inconsistencies in §9. Last verified 21 September 2026 (rev 1.5).

---

This page is generated from the file in reference/ECOCASH-EIP-API.md. Spotted something wrong? Open an issue.