By EcoCash

Disburse Change

Pay a customer their change into their EcoCash wallet at the point of sale.

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

serviceType: CHANGEDISBURSEV2

Overview

Disburse Change solves the small-change problem at the till. Where a merchant cannot give physical change, the balance is paid into the customer's EcoCash wallet instead.

How it works

The till calculates the change owed.
Your system sends a request with the customer number, the change amount, the terminal and the merchant name.
EcoCash validates your credentials, the request body, the channel code and the customer number.
On success the change is credited to the customer wallet and the response is returned on the same call.
A simulated SMS is sent to the customer, naming the merchant.

Getting started

Prerequisites

A developer account with sandbox credentials.
The customer number whitelisted and OTP-verified.
A terminal identifier for the till you are integrating.

Good to know

merchantName appears in the SMS the customer receives, so send the trading name they would recognise.
terminalId is free text. Use it to trace a transaction back to a till.
The response uses timestamp, lower case. Merchant to Subscriber uses timeStamp.

Use cases

Supermarket tills where coin float runs short.
Fuel forecourts rounding to the litre.
Any retail point of sale in a low-coin environment.

Request body

REQUEST JSON BODY

{
  "serviceType": "CHANGEDISBURSEV2",
  "externalReference": "1786097300",
  "receiverNumber": "263777000000",
  "amount": "2",
  "currency": "USD",
  "transferReference": "Change Disbursement",
  "username": "epg-sandbox-user-v1",
  "password": "<encrypted>",
  "terminalId": "TestTerminal001",
  "channelCode": "800002",
  "merchantName": "Test Merchant"
}

Request parameter definition

Request parameters for Disburse Change
Name	Description	Type	Sample value
serviceType	Selects the service. Must be CHANGEDISBURSEV2.	String	CHANGEDISBURSEV2
externalReference	Unique reference generated by your system for this transaction.	String	1786097300
receiverNumber	The customer receiving the change. Must be whitelisted in sandbox.	String	263777000000
amount	Amount of change to disburse.	String	2
currency	ISO 4217 currency code. USD or ZWG.	String	USD
transferReference	Description of the transfer. Free text.	String	Change Disbursement
username	Your channel API user.	String	epg-sandbox-user-v1
password	Your API user password, encrypted.	String	<encrypted>
terminalId	Your point of sale terminal identifier. Free text.	String	TestTerminal001
channelCode	The code identifying your sending channel. Must be 800002.	String	800002
merchantName	Merchant or branch name. Appears in the customer's SMS.	String	Test Merchant

Response body

RESPONSE JSON BODY

{
  "serviceType": "CHANGEDISBURSEV2",
  "externalReference": "1786097300",
  "requestId": "7c4e1b90-2f8a-4d63-b7e5-19a3c6d80f42",
  "transactionId": "CI260807.1208.T6335239",
  "status": 200,
  "statusMessage": "Success",
  "responseCode": "00",
  "responseMessage": "Response is successfully returned.",
  "senderNumber": "263789000000",
  "senderPostBalance": "1787.36",
  "receiverName": "Test Customer",
  "receiverMsisdn": "263777000000",
  "timestamp": "2026-08-26T12:48:40.107Z",
  "amount": "2",
  "currency": "USD",
  "transferReference": "Change Disbursement"
}

Response parameter definition

Response parameters for Disburse Change
Name	Description	Type	Sample value
serviceType	The service that ran.	String	CHANGEDISBURSEV2
externalReference	Echoed from the request.	String	1786097300
requestId	Unique identifier for this API call.	UUID	7c4e1b90-2f8a-…
transactionId	EcoCash's identifier for the transaction.	String	CI260807.1208.T6335239
status	HTTP status. Numeric on this service.	Numeric	200
statusMessage	Outcome in one word.	String	Success
responseCode	Outcome code. 00 is success.	String	00
responseMessage	Outcome in full.	String	Response is successfully returned.
senderNumber	The channel number the change came from.	String	263789000000
senderPostBalance	Channel balance after the transaction. Fixed value in sandbox.	String	1787.36
receiverName	Name registered against the whitelisted number.	String	Test Customer
receiverMsisdn	The customer who received the change.	String	263777000000
timestamp	When the transaction completed. Lower case on this service.	String	2026-08-26T12:48:40.107Z
amount	Amount disbursed.	String	2
currency	Currency.	String	USD
transferReference	Echoed from the request.	String	Change Disbursement

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 800002.	Use the channel code for this service.
400	IC50103	receiverNumber 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.