Card Service

TCardService provides basic card reading and pinpad functionality via providing AIDL interface. It is a BoundedService, which is only active when another application is bounded.

Integration

Download the zip file below and extract it.

Place the cardservicebinding-release.aar library file into your project's "libs" folder and add it as dependency inside your app level build.gradle file like below and build your project in order to create build classes of library.

dependencies { implementation fileTree(dir: 'libs', include: ['*.aar']) ... }

Inside Activity

public abstract class BaseActivity extends AppCompatActivity implements CardServiceListener {

    protected CardServiceBinding cardServiceBinding;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        cardServiceBinding = new CardServiceBinding(this, this);
    }

    @Override
    protected void onDestroy() {
        //Make sure to call unBind() method when activity is finishing
        cardServiceBinding.unBind();
        super.onDestroy();
    }

    /**
     * Callback for Card Service connected method. You will not need to check whether card service is connected or not in most cases.
     * When you make an asynchronous method call on CardServiceBinding,it will be executed automatically as soon as CardService is connected.
     */
    @Override
    public void onCardServiceConnected() {

    }

    /**
     * Callback for TCardService getCard method.
     * As getCard is an asynchronous service operation, you will get the response after operation is done in this callback.
     * @apiNote Override this method in your activity in order to get card data after calling #getData() method of Card Service.
     * @param cardData: Card data json string
     */
    public void onCardDataReceived(String cardData) { }

    /**
     * Callback for TCardService getOnlinePin method.
     * As getOnlinePin is an asynchronous real time operation, you will get the response after operation is done in this callback.
     * @apiNote Override this method in your activity in order to get pin data after calling #getOnlinePin() method of Card Service.
     * @param pin: Pin string
     */
    public  void onPinReceived(String pin) {}

    /**
     * Callback for TCardService iccTakeOut method.
     * This callback will be triggered when user takes out card from pos device after you inform the user with takeOutICC() method.
     * @apiNote Override this method in your activity in order to get icc take out callback after calling #iccTakeOut() method of Card Service.
     */
    public  void onICCTakeOut() {}
}

CardServiceBinding api methods

		
        // amount:
        // please provide it as 100 x Float amount.
        // example -> For 1 = provide 100, for 0.05 = provide 5
        //
        // timeout:
        // duration as seconds that will present card view and
        // detects any card types
        //
        // config:
        // reserved for future use
        void getCard(int amount, int timeout, String config);

        // action:
        // Online approval					    1
        // Online decline					    2
        // Unable go online					    3
        // Issuer referral approval             4
        // Issuer referral decline              5
        // Unable go online with specific ARC   6
        //
        // authRespCode:
        // Response Code from the host. 2 bytes.
        //
        // issuerAuthData:
        // Issuer Authentication Data from the issuer host
        //
        // issuerAuthDataLen:
        // Length of the Issuer Authentication Data
        //
        // issuerScript:
        // Issuer Script from the issuer host
        //
        // issuerScriptLen:
        // Length of the Issuer Script
        int completeEmvTxn(byte action, in byte[] authRespCode, in byte[] issuerAuthData, int issuerAuthDataLen, in byte[] issuerScript, int issuerScriptLen);

        // config:
        // emv settings xml data
        int setEMVConfiguration(String config);

        // amount:
        // please provide it as 100 x Float amount.
        // example -> For 1 = provide 100, for 0.05 = provide 5
        //
        // pan:
        // PAN of the Card
        //
        // keySet:
        // The keySet that assigned for Bank
        //
        // keyIndex:
        // The index of the key in keySet
        //
        // minLen:
        // min PIN entry len
        //
        // maxLen:
        // max PIN entry len
        //
        // timeout:
        // PIN entry timeout as Sec
        void getOnlinePIN(int amount, String pan, int keySet, int keyIndex, int minLen, int maxLen, int timeout);

        //ret: device SN as String
        String getDeviceSN();

        // timeout:
        // duration as seconds that will present take out Chip Card
        void takeOutICC(int timeout);

        //ret: EMV completion datas as JSON data
        String getEMVCompletionData();
			
			//info will be added
        void showQR(String header, String total, String QRData);
        void showSuccess(boolean isSuccess, String header);
        void showBlackScreen();

        // config:
        // emv settings xml data
        int setEMVCLConfiguration(String config);
        
        // config:
        // config pin entry
        public void getOnlinePINEx(String config)
}

getCard(...) API Details

It is used to get card (ICC, MSR, CL) according to config of the API.

Inputs

String config:

{
 "forceOnline":1,
 "fallback":1,
 "zeroAmount":1,
 "keyIn":1,
 "askCVV":1,       
 "showAmount":1,   
 "showCardScreen":1,
 "partialEMV":1, 
 "qrPay":1,  
 "emvTxnType":0,
 "emvProcessType":1,
 "reqEMVData":"575A5F245F204F84959F12",
 "cardReadTypes":6,
 "getOnlinePIN":1,
 "kmsVersion": 2,
 "keySet": 0,
 "keyIndex": 4,
 "minLen": 4,
 "maxLen": 12,
}

forceOnline: Force EMV Txns Online

fallback: Enable fallback

zeroAmount: Show the amount data on screen however send to EMV kernel amount as "0"

keyIn: Enable keyIn on getCard screen

askCVV: Enable CVV entry on keyIn screen

showAmount: Show the amount data on screen

showCardScreen: Show the Card Screen. If pre-reading has been made by the platform please set is as "0"

partialEMV: Deprecated, please use emvProcessType

qrPay: Enable QR button on Card Screen

emvTxnType: EMV Txn Type. Sale: 0x00, Return: 0x20

emvProcessType: It is used if txn is ICC. The types of the EMV process are below.

public enum emvProcessType {
    PARTIAL_EMV(0),		//After reading card data with requested Tags, requesting AAC at the 1st Generate AC to complete transaction and return requested Tag data
    READ_CARD(1),		//After app selection, read requested card data and return 
    CONTINUE_EMV(2),	//Continue and complete full EMV Txn from Read Card Data process and returns  requested Tag data.
    FULL_EMV(3);		//Actions based EMV Specification, such as Initiate App. Processing, Read App. Data, Off. Auth., Processing restrictions, Cardholder Verification, Term. Risk Man., First Gen AC and returns  requested Tag data.
}

reqEMVData: Tags that requested for ICC Read Type. ICCData fields will be filled also according to requestedEMVData.

If it is not set by user, for READ_CARD it is set to "575A5F245F204F84", for other Txn Types it is set to "575A5F245F204F9B849F125F2A5F3482959A9C9F029F039F099F109F1A9F1E9F269F279F339F349F359F369F379F418E9F069F539F0D9F0E9F0F" by default.

Note 1:Please consider, it will take more time if you request more tags. Please make optimiziation on this tag to speed up the EMV Txn.

cardReadTypes:

public enum  CardReadCombination {
    ICC,
    CL,
    MSR,
    ICC_CL,
    ICC_MSR,
    CL_MSR,
    ALL
}

getOnlinePIN: Enable Online PIN during the getCard operation only for ICC transactions..

kmsVersion :

1 : Deprecated: Compatible with 400TR and 1000TR Castles-based systems.

2 : new KMS library, compatible with all devices.

keySet : allocated keySet value of the bank. Only set for kmsVersion 1. Not needed for kmsVersion 2.

keyIndex : keyIndex value of the PIN key.

minLen: min length of the requested PIN.

maxLen: max length of the requested PIN.

resultCode Values

public enum CardServiceResult {
    SUCCESS(0),
    USER_CANCELLED(1),
    ERROR(2),
}

ICC Card Type Return


{
"resultCode":0,
"mCardReadType":1,
"mCardNumber":"5400619377106002",
"mTrack2Data":"201324001104F",
"mExpireDate":"200131",
"mTranAmount1":123,
"mTrack1CustomerName":"SARAN\/BEYHAN",
"CardSeqNum":"04",
"AC":"4E3811C48521B4DE",
"CID":"80",
"ATC":"1180",
"TVR":"0400000800",
"TSI":"E800",
"AIP":"3900",
"CVM":"410302",
"CVMList":"0000000000000000420141035E0342031F03",
"APPVer":"0002",
"AID2":"A0000000041010",
"UN":"AAC7DC6D",
"IAD":"0110A50003020000000000000000010000FF",
"IACDef":"BC70BC8800",
"IACDen":"0000000000",
"IACOnly":"BC70BC9800",
"OnlPINReq": 0,
"PINCtr":"3",
"ALLEmv":"5F2A0209495F34010482023900950504000008009A031910189C01009F02060000000001239F03060000000000009F090200029F10120110A50003020000000000000000010000FF9F1A0207929F1E0831323334353637389F26084E3811C48521B4DE9F2701809F3303E0F0C89F34034103029F3501229F360211809F3704AAC7DC6D8E120000000000000000420141035E0342031F039F0607A00000000410109F5301529F0D05BC70BC88009F0E0500000000009F0F05BC70BC9800"
"pinData": "79D586AE6F73BA96",
"ksn": ""
}

CL Card Type Return


{
   "resultCode":0,
   "mCardReadType":5,
   "mCardNumber":"4797957003463700",
   "mTrack2Data":"201337001101??",
   "mExpireDate":"250731",
   "mTranAmount1":50000,
   "CardSeqNum":"01",
   "AC":"8D402D28A939C4B3",
   "CID":"80",
   "ATC":"016C",
   "TVR":"0000000000",
   "TSI":"0000",
   "AIP":"2000",
   "CVM":"020000",
   "AID2":"A0000000031010",
   "UN":"FDB2E2AA",
   "IAD":"06011103A000000A010000021094A9129767",
   "OnlPINReq":1,
   "PINCtr":3,
   "SID":23,
   "DateTime":"20210413085810",
   "Track1Data":"%B4797957003463700^ \/^2507201100000000000?f",
   "Track2Data":";4797957003463700=2507201337001101??",
   "ALLEmv":"5A0847979570034637005F2403250731950500000000008407A00000000310109F26088D402D28A939C4B39F2701809F3602016C9B020000820220009F34030200009F3704FDB2E2AA9F101206011103A000000A010000021094A91297675F340101DF8F4F020004DF81290830F0F02090F0FF00DF8115060000000000FFDF2A06000000021094990100",
   "CVMAnalysis":2,
   "TransResult":4
}

TransResult:

0x0002 //d_EMVCL_OUTCOME_APPROVAL

0x0003 //d_EMVCL_OUTCOME_DECLINED

0x0004 //d_EMVCL_OUTCOME_ONL

SID:

d_EMVCL_SID_VISA_OLD_US                      0x13
d_EMVCL_SID_VISA_WAVE_2                      0x16
d_EMVCL_SID_VISA_WAVE_QVSDC                   0x17
d_EMVCL_SID_VISA_WAVE_MSD                     0x18
d_EMVCL_SID_PAYPASS_MAG_STRIPE                 0x20
d_EMVCL_SID_PAYPASS_MCHIP                     0x21
d_EMVCL_SID_JCB_WAVE_2                       0x61
d_EMVCL_SID_JCB_WAVE_QVSDC                    0x62
d_EMVCL_SID_JCB_EMV                         0x63
d_EMVCL_SID_JCB_MSD                         0x64
d_EMVCL_SID_JCB_LEGACY                       0x65
d_EMVCL_SID_AE_EMV                          0x50
d_EMVCL_SID_AE_MAG_STRIPE                     0x52
d_EMVCL_SID_DISCOVER                         0x41
d_EMVCL_SID_DISCOVER_DPAS                     0x42
d_EMVCL_SID_DISCOVER_DPAS_MAG_STRIPE             0x43
d_EMVCL_SID_INTERAC_FLASH                     0x48
d_EMVCL_SID_MEPS_MCCS                        0x81
d_EMVCL_SID_CUP_QPBOC                        0x91
d_EMVCL_SID_CB_PAGOBANCOMAT                   0x86

CVMAnalysis:

Indicate which CVM is required

Indicate which CVM is required
0x00 – None.
0x01 – Signature.
0x02 – Online PIN.
0x03 – CVM Fail.
0x04 – NO CVM.
0x05 – Confirmation Code Verified.

MSR Card Type Return


{
   "resultCode":0,
   "mCardReadType":2,
   "mCardNumber":"5168881167113299",
   "mTrack2Data":"1201530011?",				//other than pan and exp date
   "mExpireDate":"2711",
   "mTranAmount1":123,
   "mTrack1CustomerName":"REMZI SEPIK",
   "Track1Data":"%B5168881167113299^SEPIK\/REMZI               ^27111201100000000153000000?",
   "Track2Data":";5168881167113299=27111201530011?"
}

KeyIn Card Type Return


{  
   "resultCode":0,
   "mCardReadType":4,
   "mCardNumber":"540061937716002",
   "mExpireDate":"2001",
   "CVV":"123",
   "mTranAmount1":100
}

mCardReadType field values

public enum CardReadType {
    NONE(0),
    ICC(1),
    MSR(2),
    ICC2MSR(3),
    KeyIn(4),
    CLCard(5);
    public final int value;
    CardReadType(int value){
        this.value = value;
    }
}

completeEMVTxn(...) API Details

Actions after Online Processing, such as External Auth., Second Gen. AC, Issuer Script Processing.

Note: All ICC transactions must be completed in 330TR with completeEMVTxn. The EMV process is not completed until completeEmvTxn is called.

Inputs

action:

Online approval(1)
    
Online decline(2)
    
Unable go online(3)
    
Issuer referral approval(4)
    
Issuer referral decline(5)
    
Unable go online with specific ARC(6)
    

authRespCode: Response Code from the host. 2 bytes.

issuerAuthData: Issuer Authentication Data from the issuer host

Input value of Tag 91 in HEX format

issuerAuthDataLen: Length of the Issuer Authentication Data

issuerScript: Issuer Script from the issuer host

Input data is T(71/72)LV + T(71/72)LV + T(71/72)LV + … in HEX format

issuerScriptLen: Length of the Issuer Script

Returns

will be added...

getOnlinePIN(...) API Details

getOnlinePIN API used to get Encrypted PIN data.

Inputs

int amount : amount of the sale.

String pan : PAN of the used card

int keySet : allocated keySet value of the bank

int keyIndex : keyIndex value of the PIN key

int minLen: min length of the requested PIN

int maxLen: max length of the requested PIN

int timeout: max PIN entry period as sec.

Returns

pinData

{  
  "resultCode": 0,
  "pinData": "79D586AE6F73BA96",
  "ksn": ""
}

getOnlinePINEx(String config) API Details

getOnlinePINEx API used to get Encrypted PIN with kmsVersion 2.

Note: Although this API is compatible with kmsVersion 1, as kmsVersion 1 has been deprecated, please use getOnlinePINEx.

Inputs

String config :

{
  "amount": 80000,
  "PAN": "4797957003463700",
  "kmsVersion": 2,
  "keySet": 0,
  "keyIndex": 4,
  "minLen": 4,
  "maxLen": 12,
  "timeout": 30
}

amount : amount of the sale.

PAN : PAN of the used card

kmsVersion :

1: Deprecated. Compatible with 400TR and 1000TR (Castles based).

2 : new KMS library, compatible with all devices.

keySet : allocated keySet value of the bank. Only set for kmsVersion 1. Not needed for kmsVersion 2.

keyIndex : keyIndex value of the PIN key.

minLen: min length of the requested PIN.

maxLen: max length of the requested PIN.

timeout: max PIN entry period as sec.

Returns

pinData

{  
  "resultCode": 0,
  "pinData": "79D586AE6F73BA96",
  "ksn": ""
}

void takeOutICC(int timeout) API Details

takeOutICC is used to warn user to take out card.

Inputs

int timeout: take out period as sec.

String getEMVCompletionData();

Used to get EMV Completion data as JSON after completeEMVTxn API called.

Returns

{
   "mCardReadType":1,
   "TVR":"0080000800",
   "TSI":"F800",
   "AC":"2CE514F25583D648",
   "CID":"40",
   "ATC":"16B0",
   "IAD":"06010A03642002"
}

Settings

setEMVConfiguration(...) API Details

setEMVConfiguration API sets the configuration settings of Banking App to kernel.

Note: The setEMVConfiguration should be called first and followed by the setEMVCLConfiguration.

Inputs

String config

Developer can create an xml file that is formatted like

You can see how the config file is created with the examples in this document.

Returns

will be added...

setEMVCLConfiguration(...) API Details

setEMVCLConfiguration API sets the Contactless configuration settings of Banking App to kernel.

Inputs

String config

Developer can create an xml file that is formatted like

You can see how the config file is created with the examples in this document.

You can also use this document to create tag combinations in the contactless config file.

Edit: Please set "0002" parameter in xml file, according to your timeout hex formatted and msecs.

For 30 secs it is set to 30000 as below.

<ParametersConfig>
<Item ParaIndex="0002">7530</Item>
 .
 .

Config XML files updated for AMEX.

Returns

will be added...

Compatible Version Info

330TR:

APK Ver.DetailDateOTA VersionBSP Ver.

v340

Card screen animation removed

18.03.2024

v1050

-

v350

CL Track2Data error fix.

10.05.2024

v1150

-

v351

CL Tag DF81129 fix.

13.05.2024

-

-

400TR:

APK Ver.DetailDateOTA VersionBSP Ver.

v123

12.03.2024

v6.3.59

-

1000TR:

APK Ver.DetailDateOTA VersionBSP Ver.

v68

28.02.2024

v7.3.87

-

For detailed version information, you can visit the page below.

Platform Versions

Last updated