Documentation
WebsiteHelp
Start typing to search…

Transaction Search

What is a Transaction Search?

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

If a transaction UUID IS provided, the system will return the transaction details corresponding to that specific UUID, there are two methods that can be used:

  • Specifying the UUID in the endpoint.
  • Specifying the UUID in the request body.

If a transaction UUID IS NOT provided in the request body, 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.

📘

Note:

Every transaction search request needs to include Authentication

Transaction Search Request

Example: Transaction Search (UUID Specified in Endpoint)

GET

posbuddy-cloud/v/1/transaction/{UUID}

  • i.e. posbuddy-cloud/v/1/transaction/bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc

Example: Transaction Search (UUID not Specified)

POST

posbuddy-cloud/v/1/transaction

BODY

The following is an example of a TX_SEARCH request body

{
    "launchType": "TX_SEARCH",
    "merchantID": "merchantID",
    "posId": "posId",
    "serialNumber": "serialNumber",
}
String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("launchType", "TX_SEARCH");
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "transaction")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();
# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/v/1/transaction" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"launchType\": \"TX_SEARCH\",
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\"
  }" \
 )

Example: Transaction Search (UUID Specified in Body)

POST

posbuddy-cloud/v/1/transaction

BODY

The following is an example of a TX_SEARCH request body

{
    "launchType": "TX_SEARCH",
    "merchantID": "merchantID",
    "posId": "posId",
    "serialNumber": "serialNumber",
    "extraParameters": {
      "transactionUuid" : "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc"
     }
}
String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject extraParameters = new JSONObject();
extraParameters.put("transactionUuid", UUID.randomUUID().toString());

JSONObject requestBody = new JSONObject();
requestBody.put("launchType", "TX_SEARCH");
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);
requestBody.put("extraParameters", extraParameters);

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "transaction")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();
# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/v/1/transaction" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"launchType\": \"TX_SEARCH\",
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\",
    \"extraParameters\": {
      \"transactionUuid\": \"0c116ebf-53e0-465d-afad-6c174a4abb49\"
    }
  }" \
 )

Request Body Fields

The following table describes the REQUIRED request body fields of the TX_SEARCH request message.

FIELD

TYPE

DESCRIPTION

EXAMPLE

REQUIRED

launchType

STRING

Must be “TX_SEARCH”.
Used for launching the Ecentric Payment App to perform a transaction search query.

  • The TX_SEARCH launchType is only required in the request body when making use of the following requests:
  • See Example: Transaction Search (UUID not Specified).
  • See Example: Transaction Search (UUID Specified in Body)_

TX_SEARCH

merchantID

STRING

The merchant ID assigned to the merchant.
The merchant ID will always be the same ID for a specific merchant.
To be provided by Ecentric.

910100000000001

posId

STRING

The POS ID is a unique identifier for the originating Point of Sale terminal. In multi-terminal environments, each device requires a distinct alphanumeric identifier (e.g., POS1, POS2, CHECKOUT_A).

POS-STORE123-TERM01

serialNumber

STRING

The serial number of the target payment terminal for this payment request.

PC05P2CG10036

extraParameters Object

The following table describes the OPTIONAL extraParameters object of the TX_SEARCH request message.

FIELD

TYPE

DESCRIPTION

EXAMPLE

transactionUuid

STRING

A Universally Unique Identifier (UUID) assigned to each transaction so it can be uniquely tracked, referenced, or correlated across different systems. Most programming languages provide built-in functions to generate UUIDs. Examples:
// Java
String transactionUuid = UUID.randomUUID().toString();

// Kotlin
val transactionUuid = UUID.randomUUID().toString()

// JavaScript
const transactionUuid = crypto.randomUUID();

`# Pythontransaction_uuid = str(uuid.uuid4())_The transactionUuid is only required in the request body when making use of the following requests:

  • See Example: Transaction Search (UUID Specified in Body)_

TX_SEARCH

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

Transaction Search Response

Result Codes

RESULTCODEDESCRIPTION
01Successful
02Declined
04Error occurred

Example: Transaction Search

BODY

The following is an example of a TX_SEARCH response body the POS Application will receive.

📘

Note:

When making use of the posbuddy-cloud/v/1/transaction/{UUID} endpoint where the UUID is present in the endpoint and not the body, the response will look similar to the TX_SEARCH response, with the only exception being that the "launchType": "TX_SEARCH" field will not be populated.

{
    "resultDescription": "APPROVED",
    "buildInfo": "Ecentric",
    "isReceiptDataAvailable": true,
    "resultCode": "01",
    "receiptBundle": {
      "MERCHANT_REGION_CODE": "09",
      "RC_ALT": "00",
      "CASH_AMOUNT_CENTS": "0",
      "SEQ_NO": "000",
      "STATUS": "APPROVED",
      "BUDGET_PERIOD": "0",
      "CARD_TYPE": "",
      "PAN_WITH_BIN": "445143******2309",
      "MERCHANT_ID": "770000000000123",
      "TIMESTAMP": "1745476020950",
      "EXTERNAL_TRANSACTION_DATETIME": "",
      "PROCESSING_CODE": "0",
      "RC_DESCRIPTION": "Approved",
      "EXTERNAL_INVOICE_GUID": "",
      "REPLACEMENT_MERCHANT_ID": "",
      "BATCH_NO": "000",
      "AUTH_PROFILE": "0",
      "INTERCHANGE": "null",
      "ESC_BY_AUTH_CODE": "226 00 IH 15882",
      "TX_TYPE": "0",
      "ACC_TYPE_DESC": "Default",
      "TIP_AMOUNT": "",
      "CURRENCY_CODE": "0710",
      "AUTH_CODE": "15882",
      "RC": "00",
      "AID": "A0000000031010",
      "ATC": "055D",
      "CRY": "13A531FAFC4D29F6",
      "CVM": "none",
      "IAD": "06010A03A04000",
      "PAN": "************2309",
      "RRN": "511427060006",
      "TSI": "0000",
      "TVR": "0000000000",
      "APSN": "",
      "DATE": "2025-04-24T06:27:06.749+0000",
      "STAN": "",
      "NAME_ON_CARD": "UnknownCardholderName",
      "AMOUNT_CENTS": "1000",
      "ABS_AMOUNT": "10.00",
      "TOKEN": "",
      "RECEIPT_NUMBER": "",
      "EXTENDED_TRX_TYPE": "",
      "TERMINAL_ID": "77012398",
      "TX_TYPE_DESCRIPTION": "DEBIT",
      "EXTERNAL_TERMINAL_ID": "",
      "FORMATTED_AMOUNT": "R 10.00",
      "DESCRIPTION": "511427060006",
      "BATCH_NUMBER": "0",
      "SETTLEMENT_DATE": "",
      "SURCHARGE_AMOUNT": "0.00",
      "EXTERNAL_TRANSACTION_GUID": "",
      "CARD_BIN": "445143",
      "TRANSACTION_INFO": "22600IH15882",
      "REPLACEMENT_TERMINAL_ID": "",
      "POS_ENTRY": "701",
      "RC_ISO_DESCRIPTION": "Approved or completed successfully",
      "APPLICATION_LABEL": "VISA SAVINGS",
      "MERCHANT_CITY": "Cape Town",
      "MERCHANT_NAME": "Istore",
      "CUSTOMER_NAME": "",
      "APP_VERSION": "",
      "CARD_SEQ_NO": "0",
      "APP_LABEL": "VISA SAVINGS",
      "INVOICE_NUM": "",
      "MESSAGE_1": "",
      "MESSAGE_2": "",
      "CARD_TRANSACTION_TYPE": "CONTACTLESS",
      "FORMATTED_CASH_AMOUNT": "R 0.00",
      "CASH_AMOUNT": "0.00",
      "RESULT_CODE": "00",
      "MERCHANT_COUNTRY_CODE": "ZA",
      "REPRINT": "false",
      "PAN_HASH": "3f5c9f528a4bfa5d5e4137824d0b08491b5bc30b062ad778a818770f10771019",
      "AMOUNT": "10.00",
      "TIP_LABEL": "",
      "DIGITS": "2309",
      "CVM_ABSA": ""
    },
    "merchantID": "770000000000123",
    "serialNumber": "PF5544544664",
    "posId": "POS-STORE123-TERM01"
    "isApproved": "true",
    "launchType": "TX_SEARCH",
    "cashAmount": "0",
    "transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc",
    "appVersion": "1.9.2",
    "transactionAmount": "1000"
}

Response Body Fields

The following table describes the response body fields of the TX_SEARCH response message.

FIELDS

TYPE

DESCRIPTION

EXAMPLE

launchType

STRING

Echo of the launchType used in the POSBuddy Cloud request.

TX_SEARCH

resultCode

STRING

Represents the result status of the intent call to the Ecentric Payment App
● 01: SUCCESSFUL
● 02: DECLINED
● 04: ERROR

01

resultDescription

STRING

A user readable representation of the above resultCode i.e. Approved for resultCode 01.
If the bank or switch approves or declines the transaction, the response description is included in this field.

APPROVED

merchantID

STRING

Echo of the merchantID used in the request.

910100000000001

merchantName

STRING

The name of the merchant that requested the transaction as stored at the bank.

Merchant A

transactionAmount

STRING

Approved total transactionAmount.

1000

cashAmount

STRING

Approved cashAmount.

5000

transactionDescription

STRING

Echo of the transactionDescription used to launch the Ecentric Payment App.

3rd party app desc

isReceiptDataAvailable

STRING

Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.

true

receiptBundle

STRING

Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.

See TX_SEARCH response body.

appVersion

STRING

The software version currently running on the Ecentric Payment App.

1.9.2

externalSTAN

STRING

Echo of the systems trace number generated by some 3rd party ERP systems.

123456

externalRRN

STRING

Echo of the RRN generated by some 3rd party ERP systems.

ABCDEF123456

externalTransactionGUID

STRING

Echo of the GUID that identifies a specific transaction generated by 3rd party ERP systems.

2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8

externalInvoiceGUID

STRING

Echo of the GUID that identifies a particular invoice that may appear on more than one transaction.

2fdca02f-3cbe-4e8c-82ad-86a1a16b72e9

externalTransactionDateTime

STRING

Echo of the date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss”

2017-04-28T09:30:00

externalTerminalId

STRING

Echo of the terminal identifier for device configured on the 3rd party ERP system.

98100010

transactionUuid

STRING

Echo of the Unique ID of a transaction.

bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc

terminalId

STRING

This is an automatically system-assigned terminalID of the payment terminal’s identity number, which can be used to assist with settlement information and is returned in BASE36 format.

77012398

latitude

STRING

Echo of geolocation identifier indicating the latitude position of the device.

-28.1619942

longitude

STRING

Echo of geolocation identifier indicating the longitude position of the device.

30.2350981

accuracy

STRING

Echo of accuracy indicator of the geolocation.

serialNumber

STRING

The serial number for the device that was used for the RETAIL_AUTH intent call.

PC05P2CG10036

posId

STRING

Echo of the posId present in the request.

POS-STORE123-TERM01

Error Handling

Example: Errors

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

ERROR MESSAGESOLUTION
Incorrect merchantID/ not presentEnsure that you have entered the correct merchantID.
posId is not presentEnsure that you include the posId in your request.
serialNumber not presentEnsure that you include the serialNumber in you request.
Terminal <serial_number> is offlineEnsure the requested terminal is turned on and has established a valid connection to POSBuddy Cloud.
launchType not presentEnsure you provide the launchType “TX_SEARCH”

BODY

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

{	
    "resultDescription": "ERROR",
    "errorBundle": {
      "description": "ERROR",
      "reference": "",
      "errorType": "TRANSACTION",
      "message": "Error communicating with server"
    },
  "buildInfo": "Ecentric_DEBUG_Ecentric_INT",
  "isReceiptDataAvailable": "false",
  "resultCode": "04",
  "merchantID": "910100000000001",
  "serialNumber": "PC05P2CG10036",
  "posId": "POS-STORE123-TERM01",
  "launchType": "TX_SEARCH",
  "appVersion": "1.9.8"
}

Updated about 19 hours ago