By EcoCash

Enterprise Cash-In

Disburse funds into customers' EcoCash wallets in bulk.

POSThttps://developers.ecocash.co.zw/api/serviceRequest

serviceType: ENTERPRISECASHINV2

Overview

Enterprise Cash-In moves money out of your channel and into a customer's EcoCash wallet. It is built for volume: paying growers, beneficiaries, contractors or salaries in a run rather than one at a time.

How it works

Your system sends a request with the customer number, the amount and your channel code.
EcoCash validates your client credentials, then your channel API user.
EcoCash validates the request body, then the channel code, then the customer number against your whitelist.
On success the funds are credited to the customer wallet and the response is returned on the same call.
A simulated SMS is sent to the customer number.
The transaction is stored so Transaction Lookup can retrieve it later.

Getting started

Prerequisites

A developer account with sandbox credentials.
The customer number whitelisted and OTP-verified on the Test Numbers page.
Your channel API user password encrypted against your encryption key.

Good to know

The API is synchronous. The outcome comes back on the same call. There is no callback URL.
senderPostBalance is a fixed sandbox value, not a calculated balance.
receiverName is the name held against the whitelisted number, so it differs per developer.
externalReference must be unique. Reusing one returns the original transaction.

Use cases

Paying agricultural growers on delivery.
Running a payroll or a stipend cycle.
Paying out insurance claims or social grants.

Request body

REQUEST JSON BODY

{
  "serviceType": "ENTERPRISECASHINV2",
  "externalReference": "1786088141",
  "beneficiaryReference": "Grower203",
  "amount": "1",
  "currency": "USD",
  "transferReference": "ENTERPRISECASHIN",
  "msisdn": "263777000000",
  "username": "epg-sandbox-user-v1",
  "password": "<encrypted>",
  "channelCode": "700002",
  "walletId": "12"
}

Request parameter definition

Request parameters for Enterprise Cash-In
Name	Description	Type	Sample value
serviceType	Selects the service. Must be ENTERPRISECASHINV2.	String	ENTERPRISECASHINV2
externalReference	Unique reference generated by your system for this transaction. Used to look it up later.	String	1786088141
beneficiaryReference	Your own reference for the beneficiary. Free text, echoed back in the response.	String	Grower203
amount	Amount to disburse.	String	1
currency	ISO 4217 currency code. USD or ZWG.	String	USD
transferReference	Description of the transfer. Free text.	String	ENTERPRISECASHIN
msisdn	The customer receiving the funds. Must be whitelisted in sandbox.	String	263777000000
username	Your channel API user.	String	epg-sandbox-user-v1
password	Your API user password, encrypted against your encryption key.	String	<encrypted>
channelCode	The code identifying your sending channel. Must be 700002.	String	700002
walletId	Wallet type. 12 is the primary EcoCash wallet.	String	12

Response body

RESPONSE JSON BODY

{
  "serviceType": "ENTERPRISECASHINV2",
  "transactionId": "CI260807.0934.T6335049",
  "requestId": "3f2a91c4-7e5b-4a2d-9c11-8b6d0e4f7a23",
  "status": "200",
  "responseCode": "00",
  "statusMessage": "SUCCEEDED",
  "responseMessage": "Cash In transaction of USD 1 has been successfully completed between the sender: 263789000000 and receiver: 263777000000. Txn ID: CI260807.0934.T6335049. New balance: USD 44917873.90",
  "senderNumber": "263789000000",
  "senderPostBalance": "44917873.90",
  "receiverName": "Test Beneficiary",
  "receiverNumber": "263777000000",
  "timeStamp": "2026-08-26T12:48:40.107Z",
  "amount": "1",
  "currency": "USD",
  "transferReference": "ENTERPRISECASHIN",
  "beneficiaryReference": "Grower203",
  "externalReference": "1786088141"
}

Response parameter definition

Response parameters for Enterprise Cash-In
Name	Description	Type	Sample value
serviceType	The service that ran. Echoed from the request.	String	ENTERPRISECASHINV2
transactionId	EcoCash's identifier for the transaction. Quote this in any support query.	String	CI260807.0934.T6335049
requestId	Unique identifier for this API call.	UUID	3f2a91c4-7e5b-…
status	HTTP status of the request.	String	200
responseCode	Outcome code. 00 is success.	String	00
statusMessage	Outcome in one word.	String	SUCCEEDED
responseMessage	Outcome in full, in the wording EcoCash uses.	String	Cash In transaction of USD 1 …
senderNumber	The channel number the funds came from. Taken from your API user, not the request.	String	263789000000
senderPostBalance	Channel balance after the transaction. Fixed value in sandbox.	String	44917873.90
receiverName	Name registered against the whitelisted number.	String	Test Beneficiary
receiverNumber	The customer who received the funds. Echoed from msisdn.	String	263777000000
timeStamp	When the transaction completed.	String	2026-08-26T12:48:40.107Z
amount	Amount disbursed. Echoed from the request.	String	1
currency	Currency. Echoed from the request.	String	USD
transferReference	Echoed from the request.	String	ENTERPRISECASHIN
beneficiaryReference	Echoed from the request.	String	Grower203
externalReference	Echoed from the request. Use it with Transaction Lookup.	String	1786088141

Error codes

Error codes this service returns
HTTP	Code	Cause	What to do
401	SBX40100	Client Id or Client Secret missing or wrong.	Check both headers.
401	TP40101	Username or decrypted password does not match.	Check the username and the encryption key.
400	SBX40000	Something is wrong with the request body. A missing field, an unrecognised serviceType, a malformed number, a non-positive amount or an unsupported currency.	Read the message. It names the field.
400	TP40288	channelCode is not 700002.	Use the channel code for this service.
400	IC50103	msisdn is not on your whitelist.	Add and verify the number on the Test Numbers page.

Match on responseCode, not on the message text. Every code, with an example body, is on the Errors page.