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

How Does a Card Query Work?

Process Description

Step 1:

The MPOS will initiate a CARDQUERY request, the CARDQUERY request will be sent to the Ecentric Payment App.

Step 2:

The Ecentric Payment App will process the card details and forward the CARDQUERY request to the Ecentric Server.

Step 3:

The Ecentric Server will validate the card bin.

Note: If the card bin is not whitelisted, the Ecentric Server will return and error to the Ecentric Payment App.

Step 4:

Once the card bin has been validated the Ecentric Server will return the CARDQUERY response to the Ecentric Payment App.

Step 5:

The Ecentric Payment App will then forward the CARDQUERY response to the MPOS App.

Step 6:

The MPOS App will then have access to the card details.

Request

Sample Bundle

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

"authenticationKey": "e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb",
 "merchantID": "971234500000003",
 "launchType": "CARDQUERY"

Parameters

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

PARAMETER	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.	971234500000003
authenticationKey	STRING	The authentication token that was generated by the server on a successful auth call to the Ecentric Payment App	e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb

Sample Code

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

*See Sample Code CARDQUERY Response for the intentLauncher function

private void doCardQuery() {
   Intent intent = new Intent();
   intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
   Bundle dataBundle = new Bundle();
   dataBundle.putString("launchType", "CARDQUERY");
   dataBundle.putString("merchantID", "910100000000001");
   dataBundle.putString("authenticationKey", "received_authenticationKey");

   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 CARDQUERY response bundle that the MPOS Application will receive.

  "adjustAmount": 0,
  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]",
  "cashAmount": 0,
  "isReceiptDataAvailable": true,
  "launchType": "CARDQUERY",
  "merchantID": "910100000000001",
  "outstandingAmount": 0,
  "panData": "6009352937150509",
  "posId": "",
  "receiptBundle": {
    "ACC_TYPE_DESC": "Credit",
    "APPLICATION_LABEL": "",
    "BUDGET_PERIOD": "00",
    "CARD_BIN": "6009352",
    "CARD_NAME": "Cr-Samba",
    "TSI": "0000",
    "TVR": "0400008001"
  },
  "resultCode": "00",
  "resultDescription": "COMPLETED",
  "serialNumber": "F31P606437P1024",
  "track1Data": "B6009352937150509^MASS BUILD                ^260279910000        00012000000",
  "track2Data": "6009352937150509\u003d260279910000050012",
  "transactionAmount": 0,
  "transactionUuid": "b7af9bd0-0735-439a-9e0d-62a0e16e271e"

Parameters

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

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
BODY
adjustAmount	LONG	N/A for Cardquery	0
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	N/A for Cardquery	0
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.	CARDQUERY
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
outstandingAmount	LONG	N/A for Cardquery	0
panData	STRING	PAN of card if available	6009352937150509
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
resultCode	STRING	Represents the final outcome of the query. ● 00: COMPLETED ● 03: ABORTED ● 04: ERROR	00
resultDescription	STRING	A user readable representation of the above resultCode i.e. Approved for resultCode 01.	COMPLETED
track1Data	STRING	Contents of track 1 if available	"B6009352937150509^MASS BUILD ^260279910000 00012000000"
track2Data	STRING	Contents of track 2 if available	5210955001511518=29056270000000154000
transactionAmount	LONG	N/A for Cardquery	0
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
RECEIPT BUNDLE
ACC_TYPE_DESC	STRING	Description of selected account	Credit
APPLICATION_LABEL	STRING	Label of application used	MSI12 v1 0
BUDGET_PERIOD	STRING	Selected budget period for this transaction	00
CARD_BIN	STRING	Bin of the card used	6009352
CARD_NAME	STRING	Scheme name of the card used for the transaction	Cr-Samba
TSI	STRING	EMV Transaction Status Information	0000
TVR	STRING	EMV Terminal Verification Results	0400008001

Sample Code

📘
Note
There are 2 different responses that may be received when performing this function and are solely dependent on the Merchants configuration settings.

Response if the Card is not whitelisted

Response if the Card is whitelisted

The following code needs to be implemented by the MPOS Application to recover the CARDQUERY 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");
                   String track1Data = responseBundle.getString("track1Data"); 
		   String track2Data = responseBundle.getString("track2Data"); 
		   String panData = responseBundle.getString("panData");
		   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   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 CARDQUERY 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": "CARDQUERY",
"appVersion": "1.9.8"