By EcoCash

Online Payments

Collect payments from EcoCash customers in your app, on your site or at your till.

POSThttps://developers.ecocash.co.zw/sandbox/payment/v1/transactions/amount/

Overview

Online Payments moves money from a customer's EcoCash wallet to your merchant account. The customer confirms with their PIN. You can then look the transaction up, or refund or reverse it.

This is the existing EcoCash Online Payments API. It uses HTTP Basic authentication and its own endpoints, not the shared serviceRequest endpoint the four EPG services use.

How it works

Your system sends a charge request with the customer number and the amount.
EcoCash sends a PIN prompt to the customer.
The customer enters their PIN.
EcoCash processes the transaction and returns the outcome.
An SMS notification is sent to the customer.
If you supplied a notifyUrl, EcoCash posts the payment notification to it.

Getting started

Prerequisites

A developer account on the portal.
Your own sandbox username and password for Basic authentication, issued on the portal under Sandbox → Instant Payments.
A live EcoCash merchant code and merchant MSISDN for go-live.

Good to know

Authentication is HTTP Basic, not the client credential headers used by the other services.
The sandbox simulates a PIN prompt. The PIN you send decides the outcome — 0000 succeeds, 1111 is insufficient funds, 2222 is an incorrect PIN, 9999 exceeds the limit.
notifyUrl is optional. Without it you poll with the lookup endpoint.
Refund and reversal share one endpoint, selected by tranType: REF refunds, REV reverses.

Use cases

Checkout on a website or in an app.
Taking payment at a till or a POS terminal.
Refunding or reversing a payment you took earlier.

Request body

REQUEST JSON BODY

{
  "clientCorrelator": "1774252612",
  "referenceCode": "TEST_1774252612",
  "tranType": "MER",
  "endUserId": "773047653",
  "paymentAmount": {
    "charginginformation": {
      "amount": 1,
      "currency": "USD",
      "description": "Escrow Online Payment"
    },
    "chargeMetaData": {
      "channel": "WEB",
      "purchaseCategoryCode": "Online Payment",
      "onBeHalfOf": "ECOCASH"
    }
  },
  "merchantCode": "001535",
  "merchantPin": "0000",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}

Request parameter definition

Request parameters for Online Payments
Name	Description	Type	Sample value
clientCorrelator	Transaction identifier generated by your system. Must be unique per transaction.	String	1774252612
referenceCode	Reference code generated by your system.	String	TEST_1774252612
tranType	Transaction type. MER for merchant-initiated.	String	MER
endUserId	The customer's EcoCash MSISDN. Must be whitelisted under Test Numbers first.	String	773047653
paymentAmount	Nested charging information (amount, currency, description) and charge metadata.	Object	see request body
merchantCode	Your merchant identifier.	String	001535
merchantPin	Your merchant security PIN. In sandbox it selects the outcome.	String	0000
merchantNumber	Your registered merchant MSISDN.	String	788732685
countryCode	Country code.	String	ZW
terminalID	POS terminal identifier.	String	UAT00003
location	Merchant location.	String	Harare
superMerchantName	Super-merchant display name.	String	ECOCASH
merchantName	Merchant display name.	String	UAT STORE 3
notifyUrl	Callback URL for the payment notification. Optional.	URL	https://your-domain/notify

Response body

RESPONSE JSON BODY

{
  "clientCorrelator": "1774252612",
  "referenceCode": "TEST_1774252612",
  "endUserId": "773047653",
  "ecocashReference": "MP260508.1439.T0782584",
  "transactionOperationStatus": "Charged",
  "responseCode": "00"
}

Response parameter definition

Response parameters for Online Payments
Name	Description	Type	Sample value
clientCorrelator	Echoed from the request. Use it with the lookup endpoint.	String	1774252612
referenceCode	Echoed from the request.	String	TEST_1774252612
endUserId	The customer who was charged.	String	773047653
ecocashReference	EcoCash's identifier for the transaction. Quote it in any support query.	String	MP260508.1439.T0782584
transactionOperationStatus	Outcome of the charge. Charged on success.	String	Charged
responseCode	Outcome code. 00 is success.	String	00

Transaction lookup

GEThttps://developers.ecocash.co.zw/sandbox/payment/v1/{endUserId}/transactions/amount/{clientCorrelator}

Returns the current state of a charge, keyed by the customer's MSISDN and the clientCorrelator you sent. Use it when no notification arrived, or to reconcile.

REQUEST

GET https://developers.ecocash.co.zw/sandbox/payment/v1/773047653/transactions/amount/1774252612
Authorization: Basic <base64(username:password)>

RESPONSE JSON BODY

{
  "clientCorrelator": "1774252612",
  "referenceCode": "TEST_1774252612",
  "endUserId": "773047653",
  "ecocashReference": "MP260508.1439.T0782584",
  "transactionOperationStatus": "Charged",
  "responseCode": "00"
}

Refund or reversal

POSThttps://developers.ecocash.co.zw/sandbox/payment/v1/transactions/refund/

Returns a settled payment to the customer's wallet. tranType REF refunds and REV reverses. Send a fresh clientCorrelator and the ecocashReference of the original charge; the amount may not exceed it.

REQUEST JSON BODY

{
  "clientCorrelator": "1774252613",
  "referenceCode": "TEST_1774252613",
  "tranType": "REF",
  "endUserId": "773047653",
  "originalEcocashReference": "MP260508.1439.T0782584",
  "paymentAmount": {
    "charginginformation": {
      "amount": 1,
      "currency": "USD",
      "description": "Escrow Online Payment"
    },
    "chargeMetaData": { "channel": "WEB" }
  },
  "merchantCode": "001535",
  "merchantPin": "0000",
  "merchantNumber": "788732685",
  "countryCode": "ZW",
  "terminalID": "UAT00003",
  "location": "Harare",
  "superMerchantName": "ECOCASH",
  "merchantName": "UAT STORE 3"
}

RESPONSE JSON BODY

{
  "clientCorrelator": "1774252613",
  "originalEcocashReference": "MP260508.1439.T0782584",
  "ecocashReference": "MP260508.1441.R0782599",
  "transactionOperationStatus": "Refunded",
  "responseCode": "00"
}

Error codes

Error codes this service returns
HTTP	Code	Cause	What to do
400	—	Bad request parameters.	Check the request body against the parameter table.
401	—	Basic authentication failed.	Check the username and password on your credentials page.
422	—	Business rule violation, such as insufficient funds or an exceeded limit.	Read the response message. In sandbox the PIN you send selects this outcome.

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

Next steps

Testing

Charge a whitelisted number with PIN 0000 and confirm the transaction succeeds.
Charge with PIN 1111 and confirm insufficient funds, then 2222 for an incorrect PIN and 9999 for a limit breach.
Look the transaction up with its clientCorrelator, then refund it with tranType REF.

Go live

Complete the cases above, then follow the steps on the Go Live page.