What is a Card Query?

A card query is a call that will be done to an acquirer to obtain specific information about the card. This is typically used for loyalty cards.

Card query supports magstripe only and will return Track1, Track2 and PAN data in the clear if available. A card query will only return card data if the card bin has been whitelisted on the Ecentric Payment Portal.

📘
Track 2 Data
Track 2 data is encoded in a numerical format and primarily contains essential information necessary for processing store credit card transaction. This data is also stored on the magnetic stripe of the card.
The Track2 data consists of the below information:

Cardholder's card number

Expiry date

📘
Note:
Every card query request needs to include Authentication

Card Query Request

Example: Card Query

POST

posbuddy-cloud/v/1/cardquery

BODY

The following is an example of a CARDQUERY request body

{
    "launchType": "CARDQUERY",
    "merchantID": "770000000000123",
    "posId": "POS-STORE123-TERM01",
    "serialNumber": "PF5544544664"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("launchType", "CARDQUERY");
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 + "cardquery")
        .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/cardquery" \
  --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\": \"CARDQUERY\",
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\"
  }" \
 )

Request Body Fields

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

FIELD	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “CARDQUERY”. Used for launching the Ecentric Payment App to perform a card query.	CARDQUERY
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

Card Query Response

Result Codes

RESULTCODE	DESCRIPTION
00	Completed
03	Aborted
04	Error occurred

Example: Card Query

BODY

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

 {
  "resultDescription": "COMPLETED",
  "posId": "POS-STORE123-TERM01",
  "buildInfo": "Ecentric",
  "panData": "5210955001511518",
  "resultCode": "00",
  "merchantID": "910100000000001",
  "serialNumber": "PC05P2CG10036",
  "launchType": "CARDQUERY",
  "track1Data": "B5210644001512518^ /^28036270000015400000000000000000000000000000",
  "track2Data": "5210644001512518=28036270000000154000",
  "track3Data": "",
  "appVersion": "2.0.0"
}

Response Body Fields

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

FIELDS	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used in the POSBuddy Cloud request.	CARDQUERY
resultCode	STRING	Represents the result status of the intent call to the Ecentric Payment App ● 00: COMPLETED ● 03: ABORTED ● 04: ERROR	00
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
track1Data	STRING	Contents of track 1 if available	B5210955001511518^ /^29056270000015400000000000000000000000000000
track2Data	STRING	Contents of track 2 if available	5210955001511518=29056270000000154000
track3Data	STRING	Contents of track 3 if available	1234567890123456=21051234567890000000
panData	STRING	PAN of card if available	5210955001511518
appVersion	STRING	The software version currently running on the Ecentric Payment App.	1.9.2
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

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 “CARDQUERY”

BODY

The following is an example of a CARDQUERY 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": "CARDQUERY",
  "appVersion": "1.9.8"
}