Transaction Search

👍

What is a transaction lookup request?

This is a utility call that retrieves a previous transaction’s details using a transaction’s description and amount as the search parameters.

In cases where the Integrating application did not receive a response from the Payment App, the Transaction Search function allows the Integrating application to search using the UUID it provided.

👍

What is a UUID you may ask?

A UUID is simply a value which is uniquely generated by transaction.

You may see UUIDs referred to using different terms (GUID, or Globally Unique Identifier, is Microsoft's preferred semantic) but the meaning and effect remains the same.

3rd party applications need to use the following code to invoke the transaction search using the Ecentric Payment app in their code:

Lookup request

private String appURL = "payment.thumbzup.com"; 
private String appClass = "payment.thumbzup.com.IntentActivity"; 

    Intent intent = new Intent();
    intent.setClassName(appURL, appClass);
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "LASTTRANSACTION");
    // transactionAmount and transactionDescription are optional 
    // they must be supplied and if supplied must match the prior transaction 
    // if not supplied then the very last transaction is returned
    dataBundle.putString("applicationKey", "2fdca02f-3cbe-4e8c-82ad-86a1a16b72e7");
    dataBundle.putString("merchantID", "910100000000001");
    dataBundle.putString("merchantUsername", "default");
    dataBundle.putString("authenticationKey", "c282cdd3-59d2-42ff-8c96-826725a27e6e");
    dataBundle.putLong("transactionAmount", 10000);
    dataBundle.putString("transactionDescription", "3rd party app desc”);
    dataBundle.putString("transactionUuid", " 491321f4-c900-40a0-b5fa-4d8c0d7a91b7");
    
    intent.putExtra("ThumbzupBundle", dataBundle);
    startActivityForResult(intent, 0);

There are some rules you want to pay close attention to when processing a Transaction Search API call, these are as follows:

1. If both fields (transactionDescription and transactionAmount) are provided, the search is performed for a transaction that was performed with the same amount AND same description (Exact match) provided in the search request

2. If only the transactionDescription is provided without any amount, then the transaction with the transactionDescription (an exact match) is returned (if found).

3. If only an amount is provided without any transactionDescription then the most recent transaction with the provided amount is returned.

Handling the Transaction Search retrieval response from the Ecentric Payment app

When the search is complete, the actual transaction result and its receipt data are included in the response from the payment application.

The below code sample must be used to retrieve the transaction result from the Payment App.

Lookup Response

@Override
    protected void onActivityResult(int requestCode, int resCode, Intent data) {
    String result = "";
    Bundle b = new Bundle(data.getBundleExtra("thumbzupApplicationResponse"));
    if(resCode == Activity.RESULT_OK) {
        // handle ok result 
        String launchType = b.getString("launchType");
        String isApproved = b.getString("isApproved");
        String resultCode = b.getString("resultCode");
        String resultDescription = b.getString("resultDescription");
        String merchantName = b.getString("merchantName");
        Long transactionAmount = b.getLong("transactionAmount");
        Long otherAmount = b.getLong("transactionAmount");
        String transactionDescription = b.getString("transactionDescription");
        String transactionUuid = b.getString("transactionUuid");
        String transactionReferenceNo = b.getString("transactionReferenceNo");
        String cellNumberToSMSReceipt = b.getString("cellNumberToSMSReceipt");
        String emailAddressToSendReceipt = b.getString("emailAddressToSendReceipt");
        boolean isReceiptRequired = b.getBoolean("isReceiptRequired");
        boolean isReceiptDataAvailable = b.getBoolean("isReceiptDataAvailable");
        String externalSTAN = b.getInt("externalSTAN");
        String externalRRN = b.getString("externalRRN");
        String externalTransactionGUID = b.getString("externalTransactionGUID");
        String externalInvoiceGUID = b.getString("externalInvoiceGUID");
        String externalTransactionDateTime = b.getString("externalTransactionDateTime");
        String externalTerminalId = b.getString("externalTerminalId");
        
        if (isReceiptDataAvailable) { 
            // this represents extra data from card processing backend
            Bundle receiptBundle = b.getBundle("receiptBundle");
            
            Iterator it = receiptBundle.keySet().iterator();
            while (it.hasNext()) { 
                // go through extra data Object key = it.next();
                Object val = receiptBundle.get(key.toString());
            }
        }
    }
}

In an event where the search criteria do not match any transaction, the payment application returns an error (result description as ERROR, with a result code of ‘04’).
The error bundle contains the error description as ‘No Transaction Found’.

An example of this error is provided below.

Java

authenticationKey=112b253a-67aa-4369-878d-87e2f4cbb9eb
   resultDescription=ERROR
   errorBundle= [
       description=No Transaction Found.
       reference=notifyTransactionHistory
       errorType=TRANSACTION
       message=no transactions returned
   ]
   fwUpdateDate=null
   buildInfo=ECENTRIC_INT
   applicationKey=6397dead-7d4b-47f7-a0a5-71e5d1705fc4
   fwUpdateVersion=null
   pebbleFirmwareVersion=v3.1.4
   resultCode=04
   fwUpdateAvailable=false
   overrideMerchantNumber=null
   merchantID=910300000000015
   merchantUsername=default
   pebbleSerialNumber=
   B26700220006E75FFE061ACC0D
   thirdPartyUsername=null
   launchType=TX_SEARCH
   keepAliveAfterExit=0
   merchantName=Mehroze Dev