What is a Transaction Search?

The purpose of the Transaction search functionality is to retrieve details of previous transactions.

How Does a Transaction Search Work?

If a transaction UUID IS provided in the request message, the system will return the transaction details corresponding to that specific UUID.
If a transaction UUID IS NOT provided in the request message, the details of the most recent transaction performed on the terminal will be returned.

📘
Note:
Search for transactions by UUID, amount, and/or description. Returns the most recent transaction that matches all specified parameters.

Request

Sample Bundle

The following is an example of a TX_SEARCH request bundle that the MPOS Application will request.

"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"merchantID": "770000000000123"
"launchType": "TX_SEARCH"

Parameters

The following table describes the parameters of the TX_SEARCH request message.

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “TX_SEARCH” Used for launching the Ecentric Payment App to perform a transaction search query.	TX_SEARCH
merchantID	STRING	The merchant ID assigned to the merchant.	945230000000001
authenticationKey	STRING	The authentication token that was generated by the server on a successful login to the Ecentric Payment App	e27b5456-8bff6-4746-94bg-367253356eb
OPTIONAL
transactionUuid	STRING	Unique ID (UUID) of transaction if searching for a specific transaction..	79f451e7-edc9-4f9e-8625-18618f597a8f
transactionAmount	LONG	The full transaction amount to be charged in cents. This amount will include a cashAmount if it was specified.	1000
transactionDescription	STRING ALPHANUMERIC WITH SPACES	Reference description for the merchant’s records.	3rd party app desc

Sample Code

The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Payment App to initiate a TX_SEARCH request message.

*See Sample Code TX_SEARCH Response for the intentLauncher function

private void doTxSearch() {
    Intent intent = new Intent();
    intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "TX_SEARCH");
    dataBundle.putString("merchantID", "910100000000001");
  	dataBundle.putString("authenticationKey", "received_authenticationKey");
  	dataBundle.putString("transactionUuid", "78a501e7-edc9-4f9e-8625-18618f597a8f"); // Returns last transaction or specific transaction if UUID is specified

    intent.putExtra("ecentricBundle", dataBundle);
    try {
        intentLauncher.launch(intent);
    } catch (Exception e) {
        Log.e(TAG, "Error launching intent: " + e);
   }
}

Response

Sample Bundle

The following is an example of a TX_SEARCH response bundle that the MPOS Application will receive.

Receipt Bundle Section

    "adjustAmount": 10000,
    "appVersion": "2.2.0",
    "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]",
    "cashAmount": 0,
    "isReceiptDataAvailable": true,
    "launchType": "TX_SEARCH",
    "merchantID": "910100000000001",
    "outstandingAmount": 0,
    "posId": "",
    "receiptBundle": { Please see receipt bundle section
    },
    "resultCode": "01",
    "resultDescription": "APPROVED",
    "serialNumber": "F31P606437P1024",
    "transactionAmount": 10000,
    "transactionLinkIdentifier": "1234567890123456789012",
    "transactionUuid": "d3d61b97-89b1-4543-8a43-b9c5db34af5f",
    "txType": "DEBIT"

Parameters

The following table describes the parameters of the TX_SEARCH response message.

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
adjustAmount	LONG	Amount in cents to adjust the transactionAmount after the transaction, can be positive or negative. Tipping example: Tip of R20.00 → adjustAmount = 2000 Loyalty example: Redeems R50.00 with loyalty card → adjustAmount = -5000 Sale example: Sale success for R10.00 → adjustAmount = -1000 Sale declined → adjustAmount = 0	10000
appVersion	STRING	The software version currently running on the Ecentric Payment App.	2.0.0
buildInfo	STRING	Metadata that identifies the specific software build running on the payment device.	com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]
cashAmount	LONG	Approved cashAmount.	500
isReceiptDataAvailable	STRING	Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.	true
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	TX_SEARCH
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
outstandingAmount	LONG	transactionAmount + adjustAmount Tipping example: Tip of R1.50 to R10.00: transactionAmount = 1000 adjustAmount = 150 outstandingAmount = 1150 Sale example: Sale success of R10.00 transactionAmount = 1000 adjustAmount = -1000 outstandingAmount = 0	0
posId	STRING	N/A for Companion API Integrations
receiptBundle	STRING	Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.	See Receipt Bundle Section
resultCode	STRING	Represents the final outcome of the query. ● 01: SUCCESSFUL ● 02: DECLINED ● 04: ERROR	01
resultDescription	STRING	A user readable representation of the above resultCode i.e. Approved for resultCode 01.	APPROVED
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036
transactionAmount	LONG	Approved total transactionAmount.	1000
transactionLinkIdentifier	STRING	Mastercard Only The transactionLinkIdentifier is returned in the response message. The POS is responsible for storing this value if unmatched refunds need to be processed. Please see Refund Transaction for more information.	123456
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
txType	STRING	Transaction type	DEBIT

Sample Code

The following code needs to be implemented by the MPOS Application to recover the TX_SEARCH transaction outcome and resume the MPOS App flow accordingly.

When the response is returned the calling app needs to override the onActivityResult() method and can be done as follows:

private final ActivityResultLauncher<Intent> intentLauncher = registerForActivityResult(
       new ActivityResultContracts.StartActivityForResult(),
       result -> {
           if (result.getResultCode() == Activity.RESULT_OK) {
               Intent data = result.getData();
               if (data != null) {
                   Bundle responseBundle = new Bundle(data.getBundleExtra("ecentricApplicationResponse"));
                   String launchType = responseBundle.getString("launchType");
                   String resultCode = responseBundle.getString("resultCode");
                   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   if (success && launchType.matches("RETAIL_AUTH")) {
                       authenticationKey = responseBundle.getString("authenticationKey");
                   }

                   if (responseBundle.get("errorBundle") != null) {
                       Bundle errorBundle = new Bundle(responseBundle.getBundle("errorBundle"));
                   }
               }
           } else {
               Log.e(TAG, "Received error resultCode: " + result.getResultCode());
           }
       }
);

Error Handling

The following table contains typical errors that might occur and how to handle these errors:

ERROR MESSAGE	SOLUTION
Incorrect merchantID	Ensure that you have entered the correct merchantID.
authenticationKey is invalid	When your authenticationKey is invalid, you will receive an error message indicating that the authenticationKey is invalid, a RETAIL_AUTH request needs to be done to obtain a valid authenticationKey.

Sample Bundle

The following is an example of a TX_SEARCH ERROR response bundle that the MPOS Application will receive.

"resultDescription": "ABORTED",
"errorBundle": {
    "description": "ERROR",
    "reference": "",
    "errorType": "OTHER",
    "message": "Transaction cancelled by user"
  },
"buildInfo": "Ecentric_DEBUG_Ecentric_INT",
"resultCode": "03",
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"launchType": "TX_SEARCH",
"appVersion": "1.9.8"