ECOCASH ONLINE PAYMENTS

[SPECIFICATION DOCUMENT]

[Version: 5]
[Date: February 2022]

1
 Spec Document
1.0 Introduction
The Pay-Online API allows third parties to integrate and charge Ecocash subscribers for services provided. The API allows you to do the
following:
1. Charge a subscriber for a Merchant Payment
2. Refund a subscriber
3. Query a transaction
NB: The API does not allow for automatic reversals. Any reversals are managed through the Ecocash call center. Subscriber information
is also not accessible through the API.

2.0 Authentication
HTTP Basic Authentication is used for every request. A username and password will be provided.

3.0 Replay Prevention

Each POST to the API has a unique clientCorrelator which is used to differentiate requests. This field should be UNIQUE for any
transaction. A ServiceError will be returned if a duplicate clientCorrelator is POSTed.

4.0 Formats & Content Types

The API supports application/json and application/xml content types for POST operations.

NB: The POST operations have been in this document as application/json. You can also use XML in the request body.

2
 Spec Document
5.0 Charging a Subscriber
This is used to debit the subscriber’s EcoCash wallet and credit the specified Merchant.
Resource URI https://payonline.econet.co.zw/ecocashGateway-preprod/payment/v1/transactions/amount
HTTP Method POST
Operation Charge a subscriber
Response A JSON/XML representation of an amountTransaction object or ServiceError object.
NB: A different Resource URI for testing may be provided.

Sample JSON Request:

{ "clientCorrelator":"12-yt-344534454565",
"notifyUrl":"http://mysite.com/notifyURL",
"referenceCode":" REF-12345",
“tranType”,”MER”,
"endUserId":"263774222998",
“remarks”:”test remarks”,
"transactionOperationStatus":"Charged",
"paymentAmount":{
"charginginformation":{
"amount":25, "currency":"ZWL",
"description":"Paynow Online Payment"
},
"chargeMetaData":{
"channel":"WEB", "purchaseCategoryCode":"Online Payment",
"onBeHalfOf":"Paynow Topup"
}
},
"merchantCode":" 019919",
"merchantPin":"4827",
"merchantNumber":" 783361344",
“currencyCode”:”ZWL”,
“countryCode”:”ZW”,
“terminalID”:”TERM123456”,

3
 Spec Document

“location”:”1906 Borrowdale Road”,

“superMerchantName”:”CABS”,
“merchantName”:”Pick and Pay”,
}

Parameter Description
Parameter Name Description Optional/Mandatory
endUserId (string) Subscriber MSISDN. Mandatory
remarks (string) Transaction description Optional*
amount (decimal) Amount to be debited from EcoCash. Optional *
currency (string) currency identifier as defined in [ISO4217]. (“USD” or Optional *
“ZWL”)
referenceCode (string) Use this field to set your reference code. Mandatory
merchantCode (string) As provided from Ecocash Mandatory
merchantPin (string) As provided from Ecocash Mandatory
merchantNumber (string) As provided from Ecocash Mandatory
(string) Use this field to parse the original EcoCash reference of the
originalEcocashReference transaction to be reversed. This is mandatory for a Refund Optional
transaction
(string) Shows the status of the charge request. Possible values are:
CHARGED – the initial status of a charge request/transaction
COMPLETED – when transaction has been approved by the
transactionOperationStatus subscriber Mandatory
FAILED – when transaction has been rejected by the subscriber.
NB: A HTTP POST whose body is the amountTransaction is done to
the notifyUrl when this field changes to COMPLETED/FAILED.
(URI) URL used by the API to notify your application about
notifyUrl Mandatory
completion of a transaction.
channel (string) Set this field to WEB Mandatory

4
 Spec Document

(string) uniquely identifies this charge request. Duplicate

clientCorrelation
clientCorrelation value will result in a ServiceError returned. Mandatory
(string) Transaction Type Code e.g. MER= Merchant Payment,
tranType Mandatory
REF= Refund
countryCode (string) Use this field to set your reference code. Mandatory
currencyCode (string) currency identifier as defined in [ISO4217] (“USD” or Mandatory
“ZWL”)
terminalID (string) Unique identifier of terminal (POS, mPOS, etc) Mandatory
(string) Used to parse address of physical location of
location Mandatory
terminal/merchant
superMerchantName (string) Use this field to set the super merchant name Mandatory
merchantName (string) Use this field to set your merchant name in full Mandatory
reservedField1 (string) Field reserved for future use Optional
reservedField2 (string) Field reserved for future use Optional
reservedField3 (string) Field reserved for future use Optional
reservedField4 (string) Field reserved for future use Optional
reservedField5 (string) Field reserved for future use Optional
reservedField6 (string) Field reserved for future use Optional
reservedField7 (string) Field reserved for future use Optional
reservedField8 (string) Field reserved for future use Optional
reservedField9 (string) Field reserved for future use Optional
reservedField10 (string) Field reserved for future use Optional
6.0 Refund/Reversal API
This is used to credit the subscriber’s EcoCash wallet and debit the specified Merchant.
Resource URI https://payonline.econet.co.zw/ecocashGateway-preprod/payment/v1/transactions/refund
HTTP Method POST

5
 Spec Document

Operation Charge a subscriber

Response A JSON/XML representation of an amountTransaction object or ServiceError object.

NB: A different Resource URI for testing may be provided.

Sample JSON Request:

{
"clientCorrelator": "DPO-20220825-0044",
"referenceCode": "TEST-REF-0000056",
"endUserId": "263774222021",
"originalEcocashReference": "MP220825.1002.A00218",
"tranType": "REF",
"endUserId": "263774222021",
"remarks": "test Refund",
"paymentAmount": {
"charginginformation": {
"amount": 13,
"currency": "ZWL",
"description": "Paynow Online Payment"
},
"chargeMetaData": {
"channel": "SMS",
"purchaseCategoryCode": "SOAPUI test",
"onBeHalfOf": "developer"
}
},
"merchantCode": "019919",
"merchantPin": "4827",
"merchantNumber": "783361344",

6
 Spec Document

"currencyCode": "ZWL",
"countryCode": "ZW",
"terminalID": "TERM123456",
"location": "1906 Borrowdale Road",
"superMerchantName": "CABS",
"merchantName": "Pick and Pay"
}
Parameter Description
Parameter Name Description Optional/Mandatory
endUserId (string) Subscriber MSISDN. Mandatory
remark (string) Transaction description Optional*
originalEcoCashReference (string) The EcoCash transaction reference to be reversed Mandatory
amount (decimal) Amount to be debited from EcoCash. Optional *

referenceCode (string) Use this field to set your reference code.

currency (string) currency identifier as defined in [ISO4217]. ((“USD” or “ZWL”) Optional *

merchantCode (string) As provided from Ecocash Mandatory
merchantPin (string) As provided from Ecocash Mandatory
merchantNumber (string) As provided from Ecocash Mandatory
(string) Shows the status of the charge request. Possible values are:
CHARGED – the initial status of a charge request/transaction
COMPLETED – when transaction has been approved by the subscriber
transactionOperationStatus FAILED – when transaction has been rejected by the subscriber. NB: A Mandatory
HTTP POST whose body is the amountTransaction is done to the notifyUrl
when this field changes to COMPLETED/FAILED.

(URI) URL used by the API to notify your application about completion of
notifyUrl
a transaction.
channel (string) Set this field to WEB Optional

7
 Spec Document

(string) uniquely identifies this charge request. Duplicate clientCorrelation

clientCorrelation Mandatory
value will result in a ServiceError returned.
(string) Transaction Type Code e.g. MER= Merchant Payment, REF=
tranType Mandatory
Refund
countryCode (string) Use this field to set your reference code. Mandatory
currencyCode (string) currency identifier as defined in [ISO4217]. ((“USD” or “ZWL”) Mandatory
terminalID (string) Unique identifier of terminal (POS, mPOS, etc) Mandatory
location (string) Used to parse address of physical location of terminal/merchant Mandatory
superMerchantName (string) Use this field to set super merchant name Mandatory
merchantName (string) Use this field to set your merchant name in full Mandatory
reservedField1 (string) Field reserved for future use Optional
reservedField2 (string) Field reserved for future use Optional
reservedField3 (string) Field reserved for future use Optional
reservedField4 (string) Field reserved for future use Optional
reservedField5 (string) Field reserved for future use Optional
reservedField6 (string) Field reserved for future use Optional
reservedField7 (string) Field reserved for future use Optional
reservedField8 (string) Field reserved for future use Optional
reservedField9 (string) Field reserved for future use Optional
reservedField10 (string) Field reserved for future use Optional
7.0 Query the status of a charge request/transaction
Resource https://payonline.econet.co.zw/ecocashGateway-
URI preprod/payment/v1/{endUserId}/transactions/amount/{clientCorrelato r}
HTTP
GET
Method

Operation Query if a user has been charged for a transaction

Response A json/xml representation of an amountTransaction or ServiceError object.

8
 Spec Document
8.0 ServiceError
In addition to the usual HTTP Error codes, the gateway may respond with a json/xml ServiceError object. The text field of the ServiceError
gives a description of the exact error.

{
"messageId": "SVC0002",
"text": " Invalid input value for message part %1"
}