By EcoCash
Getting Started
Learn how to set up and integrate EcoCash APIs into your application and start moving money today.
Introduction
Welcome to the EcoCash APIs. EcoCash moves money for millions of people in Zimbabwe. These APIs open that same capability to your product: collecting payments, paying money out, and reconciling what you have sent.
In this release we provide endpoints for collections, bulk disbursement, change disbursement, merchant payouts and transaction lookup. The APIs are RESTful, using POST with JSON-encoded request parameters and responses, including errors.
Our APIs comply with HTTP status codes as defined in RFC 2616. You can call them from a REST client such as Postman, or from the command line with cURL.
Every transaction in the sandbox is simulated. No real money moves.
Terminologies
| Term | Meaning |
|---|---|
| EcoCash | A mobile money service in Zimbabwe for storing and transferring money by mobile phone. |
| MSISDN | A customer's mobile number. Accepted as 263XXXXXXXXX or 07XXXXXXXX and normalised automatically. |
| serviceType | The field in the request body that selects which service runs. All four EPG services share one endpoint, so this field is what distinguishes them. |
| Client credentials | A client Id and client secret, sent as headers. They identify and authorize your application. |
| Channel API user | A username and encrypted password, sent in the request body. It identifies the channel making the transaction. |
| channelCode | The code identifying the channel a transaction is sent from. Each service validates its own. |
| externalReference | A reference your own system generates for each transaction. You use it later to look the transaction up. |
| walletId | The wallet type funds are moved into. 12 is the primary EcoCash wallet. |
| Whitelist | The list of customer numbers your sandbox account may send funds or notifications to. |
| API Console | The in-portal console where you send requests and see responses without writing code. |
| Test script | The record of your API Console calls. The portal writes it as you test, and it is required to request production access. |
| EPG | EcoCash Payment Gateway. It sits behind the production APIs. |
Base URL
Sandbox
https://developers.ecocash.co.zw/api/serviceRequestEnterprise Cash-In, Disburse Change, Merchant to Subscriber and Transaction Lookup all post to this one endpoint. The serviceType field in the request body decides which service runs. There are no separate paths to configure.
Online Payments uses its own endpoints, documented on its own page.
Your production endpoints are sent to you when your go-live request is approved.
Service types
| Service | serviceType |
|---|---|
| Enterprise Cash-In | ENTERPRISECASHINV2 |
| Disburse Change | CHANGEDISBURSEV2 |
| Merchant to Subscriber | MERCHTOSUBV2 |
| Transaction Lookup | EXTERNALTRANSACTIONLOOKUP |
Your credentials
Create a developer account and request sandbox access. Five values are issued to you.
| Field | Where you get it |
|---|---|
| X-Client-Id | Returned immediately when you request sandbox access |
| X-Client-Secret | Sent to your developer inbox |
| username | Returned immediately. Your channel API user |
| password | Sent to your developer inbox. Always sent encrypted, never in clear |
| Encryption key | Sent to your developer inbox. Used to encrypt the password |
Full detail is on the Authorization page.
Channel codes
Each service validates its own channel code. Any other value returns TP40288.
| Service | channelCode |
|---|---|
| Enterprise Cash-In | 700002 |
| Disburse Change | 800002 |
| Merchant to Subscriber | 800004 |
| Transaction Lookup | not used |
Test numbers
Any customer number you send funds or a notification to must be whitelisted against your account first. You whitelist and verify numbers inside the portal.
Nothing is deducted from a whitelisted number, and no real money moves. A number that is not on your whitelist returns IC50103.
externalReference
- Must be unique per transaction.
- Used to look the transaction up afterwards.
- Reusing a reference returns the existing transaction rather than creating a new one.
The services are idempotent on this field. If a request times out and you do not know whether it went through, send it again with the same reference. You get the original transaction back, not a second one.
No PIN
The four EPG services have no PIN. The transaction completes on the API call alone, with no customer confirmation step.
Online Payments does simulate a PIN prompt. See its page for the test PIN matrix.
Going live
After testing in the sandbox you are ready for production. You will need a registered EcoCash merchant account and a completed test script. See the Go Live page.