EcoCash EIP Developer Guide

Integrate EcoCash Instant Payment step by step: charge a wallet, check the result, refund it and go live.

Where to start


Installing the skill	Install the Claude skill and let Claude write and review your EcoCash integration.
Get sandbox access	Register, get sandbox credentials from the Inbox, verify a test number.
Authentication	The Basic auth header, and where to keep credentials.
Your first payment	Charge, approve, look up and refund with cURL, start to finish.
API reference	Every endpoint, field, response and HTTP status.
Statuses & errors	Transaction statuses and error codes E001-E015, and which to retry.
Sandbox testing	PIN test matrix, test numbers, merchant values and the test checklist.
SDKs & code examples	Tested clients for PHP/Laravel, Node.js, Python, Java and C#.
Going live	Merchant validation, test evidence and the production request.
Troubleshooting	Something is broken right now. Symptom-to-cause table.
Known portal issues	Where the portal contradicts itself, and what to do.
About this guide	Repository layout, sources and licence.
Portal reference	The portal’s own Documentation and SDK tabs, verbatim.

Overview

EcoCash Instant Payment (EIP) is EcoCash’s online payment gateway. Your server asks EcoCash to charge a customer’s EcoCash wallet. EcoCash sends the customer a USSD PIN prompt on their phone, the customer approves with their EcoCash PIN, and you get the result by callback or by looking the transaction up.

1.1 What you can do

Operation	Endpoint	Use it to
Charge	`POST /transactions/amount/`	Request a payment from a customer’s EcoCash wallet
Look up	`GET /{endUserId}/transactions/amount/{clientCorrelator}`	Get the current status of a charge
Refund / reverse	`POST /transactions/refund/`	Return money for a completed payment

1.2 How a payment works

 Your server                     EcoCash EIP                     Customer's phone
     │  1. POST /transactions/amount/  │                                 │
     │ ──────────────────────────────▶ │  2. USSD PIN prompt             │
     │  ◀── 200 OK, status: PENDING ── │ ──────────────────────────────▶ │
     │                                 │  3. Customer enters PIN         │
     │                                 │ ◀────────────────────────────── │
     │  4a. Callback to your notifyUrl │                                 │
     │ ◀────────────────────────────── │  5. SMS with the outcome        │
     │  4b. …or poll GET lookup        │ ──────────────────────────────▶ │
     │ ──────────────────────────────▶ │                                 │
     │  ◀── status: SUCCESS / FAILED ─ │                                 │

A charge is asynchronous. The first response only means accepted. The payment succeeds or fails later, when the customer responds to the PIN prompt.

1.3 Quick facts


Sandbox base URL	`https://developers.ecocash.co.zw/sandbox/payment/v1`
Authentication	HTTP Basic: `Authorization: Basic base64(username:password)`
Format	HTTPS / REST, `Content-Type: application/json`
Transaction types (`tranType`)	`MER` merchant charge · `REF` refund · `REV` reversal
Currencies	`USD`, `ZWG`
Rate limit	500 requests per minute
Version	v1.0.0 (Stable)
Developer portal	https://developers.ecocash.co.zw/portal

The sandbox simulates every transaction. No real money moves.

1.4 The integration path

Get sandbox access. Register, request credentials, and verify a test number.
Set up authentication with the credentials from your portal Inbox.
Make your first payment: charge, check the status, refund.
Build it into your app using the language examples.
Test every scenario with the sandbox PIN matrix.
Go live: submit your test evidence and get production credentials.

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