By EcoCash

Transaction Lookup

Retrieve a transaction you created earlier, using your own reference.

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

serviceType: EXTERNALTRANSACTIONLOOKUP

Overview

Transaction Lookup answers one question: what happened to the transaction I sent? Use it to reconcile at the end of a run, or to recover the outcome of a call whose response you never received.

It searches on the externalReference your system generated, so you do not need to have stored anything EcoCash returned.

This service needs client credentials only. There is no channel API user and no channel code, because it does not move funds.

How it works

Your system sends a request with the reference of the transaction you are looking for.
EcoCash validates your client credentials.
EcoCash matches the reference against the transactions stored from the other services.
If there is a match, the stored transaction is returned. If not, 888803 is returned.

Getting started

Prerequisites

A developer account with sandbox credentials.
A transaction created earlier by one of the other services.

Good to know

Failed transactions are not stored, so a lookup for one returns 888803.
The not-found body returns status as a string and carries no exception field, unlike the other errors.
The request carries two different references. Read the parameter table carefully.

Use cases

End of day reconciliation against your own ledger.
Recovering the outcome of a request that timed out.
Answering a customer query about a payment.

Request body

Two different references. externalReference identifies this lookup call; externalTransactionId is the transaction you are searching for. This is the field developers get wrong most often.

REQUEST JSON BODY

{
  "serviceType": "EXTERNALTRANSACTIONLOOKUP",
  "externalReference": "1786088200",
  "externalTransactionId": "1786088141",
  "currency": "USD",
  "msisdn": "263777000000"
}

Request parameter definition

Request parameters for Transaction Lookup
Name	Description	Type	Sample value
serviceType	Selects the service. Must be EXTERNALTRANSACTIONLOOKUP.	String	EXTERNALTRANSACTIONLOOKUP
externalReference	A unique reference for this lookup call. Not the transaction you are searching for.	String	1786088200
externalTransactionId	The externalReference of the transaction you are looking up.	String	1786088141
currency	Currency of the transaction being looked up.	String	USD
msisdn	Mobile number involved in the original transaction.	String	263777000000

Response body

RESPONSE JSON BODY

{
  "serviceType": "EXTERNALTRANSACTIONLOOKUP",
  "externalReference": "1786088200",
  "transactionId": "CI260807.0934.T6335049",
  "externalTransactionId": "1786088141",
  "status": "200",
  "statusCode": "TS",
  "statusMessage": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Transaction with external id 1786088141 retrieved successfully",
  "senderNumber": "263777000000",
  "timestamp": "2026-08-26T12:48:40.107Z"
}

Response parameter definition

Response parameters for Transaction Lookup
Name	Description	Type	Sample value
serviceType	The service that ran.	String	EXTERNALTRANSACTIONLOOKUP
externalReference	Echoed from the request. Identifies this lookup call.	String	1786088200
transactionId	EcoCash's identifier for the transaction that was found.	String	CI260807.0934.T6335049
externalTransactionId	Echoed from the request. The transaction that was searched for.	String	1786088141
status	HTTP status of the lookup.	String	200
statusCode	Status of the transaction that was found. TS is success.	String	TS
statusMessage	Status in words.	String	SUCCESS
responseCode	Outcome of the lookup. 00 is success.	String	00
responseMessage	Outcome in full.	String	Transaction with external id … retrieved successfully
senderNumber	Number involved in the original transaction.	String	263777000000
timestamp	When the original transaction completed.	String	2026-08-26T12:48:40.107Z

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.
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	888803	No transaction exists for the externalTransactionId supplied.	Check the reference. Failed transactions are not stored.

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

Next steps

Testing

Create a transaction with one of the other services and note its externalReference.
Look it up and confirm the stored transaction comes back.
Look up a reference that does not exist and confirm 888803.

Go live

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