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/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/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.
| 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: // Kotlin // JavaScript
| 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
| RESULTCODE | DESCRIPTION |
|---|---|
| 01 | Successful |
| 02 | Declined |
| 04 | Error 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": { Please see receipt bundle section
},
"merchantID": "770000000000123",
"serialNumber": "PF5544544664",
"posId": "POS-STORE123-TERM01",
"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 |
| buildInfo | STRING | Metadata that identifies the specific software build running on the payment device. | com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT] |
| 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 |
| transactionAmount | LONG | Approved total transactionAmount. | 1000 |
| cashAmount | LONG | Approved cashAmount. | 5000 |
| 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 Receipt Bundle Section |
| appVersion | STRING | The software version currently running on the Ecentric Payment App. | 1.9.2 |
| transactionUuid | STRING | Echo of the Unique ID of a transaction. | bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc |
| 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 MESSAGE | SOLUTION |
|---|---|
| Incorrect merchantID/ not present | Ensure that you have entered the correct merchantID. |
| posId is not present | Ensure that you include the posId in your request. |
| serialNumber not present | Ensure that you include the serialNumber in you request. |
| Terminal <serial_number> is offline | Ensure the requested terminal is turned on and has established a valid connection to POSBuddy Cloud. |
| launchType not present | Ensure 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 1 month ago
