By EcoCash

Merchant to Subscriber

Pay a customer directly from your merchant channel.

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

serviceType: MERCHTOSUBV2

Overview

Merchant to Subscriber sends money from a merchant channel to a customer wallet. Use it where you owe a customer rather than the other way round: a refund, a payout, a settlement.

How it works

Your system sends a request with the subscriber number, the amount and your merchant channel code.
EcoCash validates your credentials, the request body, the channel code and the subscriber number.
On success the funds are credited to the subscriber wallet and the response is returned on the same call.
A simulated SMS is sent to the subscriber, naming the merchant.

Getting started

Prerequisites

A developer account with sandbox credentials.
The subscriber number whitelisted and OTP-verified.
A merchant channel with code 800004 in sandbox.

Good to know

externalReference is numeric on this service, not a string. It is numeric in the response too.
The response returns senderName rather than senderNumber.
The response uses timeStamp with a capital S. Disburse Change uses timestamp.
All three are specific to this service. Handle them as documented rather than assuming the other services behave the same way.

Use cases

Refunding a customer who returned goods.
Paying out a marketplace seller.
Settling a claim or a rebate.

Request body

externalReference is numeric on this service — send 1787759154, not "1787759154". It comes back numeric too.

REQUEST JSON BODY

{
  "serviceType": "MERCHTOSUBV2",
  "externalReference": 1787759154,
  "amount": "170",
  "currency": "USD",
  "msisdn": "263777000000",
  "username": "epg-sandbox-user-v1",
  "password": "<encrypted>",
  "channelCode": "800004",
  "transferReference": "1749466335",
  "walletId": "12"
}

Request parameter definition

Request parameters for Merchant to Subscriber
Name	Description	Type	Sample value
serviceType	Selects the service. Must be MERCHTOSUBV2.	String	MERCHTOSUBV2
externalReference	Unique reference generated by your system. Numeric on this service, not a string.	Numeric	1787759154
amount	Amount to pay.	String	170
currency	ISO 4217 currency code. USD or ZWG.	String	USD
msisdn	The subscriber 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.	String	<encrypted>
channelCode	The code identifying your merchant channel. Must be 800004.	String	800004
transferReference	Your own reference for the transfer. Free text.	String	1749466335
walletId	Wallet type. 12 is the primary EcoCash wallet.	String	12

Response body

RESPONSE JSON BODY

{
  "serviceType": "MERCHTOSUBV2",
  "externalReference": 1787759154,
  "requestId": "7a144485-cf4e-4504-a191-c90e181b6e82",
  "transactionId": "CP260826.1752.T6347991",
  "status": "200",
  "statusMessage": "Success",
  "responseCode": "00",
  "responseMessage": "Response is successfully returned.",
  "senderName": "Test Merchant",
  "senderPostBalance": "95261.93",
  "receiverName": "Test Customer",
  "receiverNumber": "263777000000",
  "timeStamp": "2026-08-26T17:53:41.621Z",
  "amount": "170",
  "currency": "USD",
  "transferReference": "1749466335"
}

Response parameter definition

Response parameters for Merchant to Subscriber
Name	Description	Type	Sample value
serviceType	The service that ran.	String	MERCHTOSUBV2
externalReference	Echoed from the request. Numeric.	Numeric	1787759154
requestId	Unique identifier for this API call.	UUID	7a144485-cf4e-…
transactionId	EcoCash's identifier for the transaction.	String	CP260826.1752.T6347991
status	HTTP status.	String	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.
senderName	The merchant the funds came from. This service returns a name, not a number.	String	Test Merchant
senderPostBalance	Channel balance after the transaction. Fixed value in sandbox.	String	95261.93
receiverName	Name registered against the whitelisted number.	String	Test Customer
receiverNumber	The subscriber who received the funds.	String	263777000000
timeStamp	When the transaction completed. Capital S on this service.	String	2026-08-26T17:53:41.621Z
amount	Amount paid.	String	170
currency	Currency.	String	USD
transferReference	Echoed from the request.	String	1749466335

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 800004.	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.