# 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.
{% file src="/files/vmw1zbKKtBXc0DoAXHK3" %}
cardservicebinding-release.7z
{% endfile %}
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**
{% code lineNumbers="true" fullWidth="false" %}
```java
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() {}
}
```
{% endcode %}
**CardServiceBinding api methods**
{% code fullWidth="false" %}
```java
// 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)
}
```
{% endcode %}
### **getCard(...) API Details**
It is used to get card (ICC, MSR, CL) according to config of the API.
#### **Inputs**
int **amount** : amount of the sale.
int **timeout**: card read timeout as seconds.
String **config:**
{% code fullWidth="false" %}
```json
{
"forceOnline":1,
"fallback":1,
"zeroAmount":1,
"keyIn":1,
"askCVV":1,
"showAmount":1,
"extraAmount":100,
"showCardScreen":1,
"partialEMV":1,
"qrPay":1,
"emvTxnType":0,
"emvProcessType":1,
"reqEMVData":"575A5F245F204F84959F12",
"cardReadTypes":6,
"currencySymbol": 949,
"forceICCTermCurrencyCode": 0,
"getOnlinePIN":1,
"kmsVersion": 2,
"keySet": 0,
"keyIndex": 4,
"minLen": 4,
"maxLen": 12,
"isDukptKey": 0,
"extraAmount": 0,
"carPay": 0
}
```
{% endcode %}
**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.
**extraAmount:** This amount will be added to the main amount and displayed as the total amount on the screen. It will be excluded from the EMV processing. Please provide it as 100 x Float amount.
**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.
**NOTE:** X30TR does not support PARTIAL\_EMV.
```java
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:**
```json
public enum CardReadCombination {
ICC,
CL,
MSR,
ICC_CL,
ICC_MSR,
CL_MSR,
ALL
}
```
**currencySymbol:** The ISO 4217 currency numeric code to show currency symbol on cardService screens. Ex:949 for TRY, 840 for USD.
**forceICCTermCurrencyCode:** For ICC transactions, temporarily set **currencySymbol** to 5F2A.
**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.
**isDukptKey:** it is set to 1 if the PIN key is Dukpt.
**extraAmount:** This amount will be added only to the main Amount and will be showed as Total Amount on the screen. It will be excluded from EMV process.
carPay: Specifically for 1000TR, it will be sent if In Car Pay is supported.
[**Returns**](#user-content-fn-1)[^1]
**resultCode Values**
```java
public enum CardServiceResult {
SUCCESS(0),
USER_CANCELLED(1),
ERROR(2),
}
```
**ICC Card Type Return**
```json
{
"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**
```json
{
"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:**
**NOTE:** Use this value to decide if the transaction will continue offline, online, or be declined.
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**
```json
{
"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**
```json
{
"resultCode":0,
"mCardReadType":4,
"mCardNumber":"540061937716002",
"mExpireDate":"2001",
"CVV":"123",
"mTranAmount1":100
}
```
mCardReadType field values
```java
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
```json
{
"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 :
```json
{
"amount": 80000,
"PAN": "4797957003463700",
"kmsVersion": 2,
"keySet": 0,
"keyIndex": 4,
"minLen": 4,
"maxLen": 12,
"timeout": 30,
"extraAmount": 0,
"currencySymbol": 949,
"isDukptKey": 1
}
```
**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.
**extraAmount:** This amount will be added only to the main Amount and will be showed as Total Amount on the screen. It will be excluded from EMV process.
**isDukptKey:** it is set to 1 if the PIN key is Dukpt.
**currencySymbol:** The ISO 4217 currency numeric code to show currency symbol on cardService screens. Ex:949 for TRY, 840 for USD.
**Returns**
pinData
```json
{
"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**
```json
{
"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
{% file src="/files/MujFvkOe7yIbYGNwHk40" %}
emv\_config.xml
{% endfile %}
You can see how the config file is created with the examples in this document.
{% file src="/files/Ef1MEtgqjz6g4fmtdLki" %}
EMV Setting Manual
{% endfile %}
{% file src="/files/3yRQwEkn3mFLEjcExhzd" %}
{% file src="/files/iui9expjOwo2Rmlj69G0" %}
{% file src="/files/Z9chnnE1BmT0Vkr8as4V" %}
**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.
{% file src="/files/EvBs8FGT32KAiAvnWqZ0" %}
{% file src="/files/ULbJIamXrcAKRJQZoCt8" %}
EMV Contactless Setting Manual
{% endfile %}
You can also use this document to create tag combinations in the contactless config file.
{% file src="/files/3Hwqv21ubXboBMTSEHUM" %}
EMV Contactless Setting TAG Data
{% endfile %}
**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.
```xml
- 7530
.
.
```
*Config XML files updated for AMEX.*
**Returns**
will be added...
## Compatible Version Info
**330TR:**
| APK Ver. | Detail | Date | OTA Version | BSP 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 | - | - |
| v500 | -PIN Status Messages
-PINCtr Error Fix
-JCB Error Fix
-AID Label error fix
-Some EMV tags added | 20.11.2024 | v1430 | - |
| v510 | -add forceICCTermCurrencyCode flag into getCard | 29.11.2024 | v1440 | - |
| v520 | -JPY decimal digits removed.
-RUB symbol added. | 20.12.2024 | v1480 | - |
| v530 | -Currency symbol added for getOnlinePineX | 27.12.2024 | v1490 | |
| v540 | -0x5F28 Tag added for Contactless transactions | 27.01.2025 | v1530 | |
| v590 | -CVC Entry added(4 digits)
-EMV Level 3 configurations have been updated. | 09.05.2025 | v1610 | |
| v600 | -Abort transaction when Offline PIN Entry times out. | 13.06.2025 | v1630 | |
v610 | -Logs updated. | 04.07.2025 | v1670 | |
| v630 | -Logs updated | 22.09.2025 | v1770 | |
| v650 | -Visa PF34-CVM Result Tag added | 19.01.2026 | V1960 | |
**400TR:**
| APK Ver. | Detail | Date | OTA Version | BSP Ver. |
| -------- | ----------------------------------------------------- | ---------- | ----------- | -------- |
| v123 | | 12.03.2024 | v6.3.59 | - |
| v125 | -Extra amount value added getCard and getOnlinePinEx. | 12.12.2024 | v6.3.76 | |
| v126 | -CVC Entry added(4 digits CVV) | 20.03.2025 | 6.3.81 | |
| v128 | -Logs updated. | 16.06.2025 | 6.3.82 | |
| V129 | -Logs updated. | 19.11.2025 | 6.3.84 | |
| v130 | -add forceICCTermCurrencyCode flag into getCard | 09.04.2026 | 6.3.87 | |
**1000TR:**
| APK Ver. | Detail | Date | OTA Version | BSP Ver. |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | -------- |
| v68 | | 28.02.2024 | v7.3.87 | - |
| v72 | -In car payment added. | 16.12.2024 | v7.4.04 | |
| v74 | -CVC Entry added(4 digits CVV)
-Extra amount value added getCard and getOnlinePinEx.
| 29.05.2025 | v7.4.26 | |
| v76 | Pan number mask | 13.10.2025 | v7.4.36 | |
| v80 | -Combo card multiple touch error fixed.
-Online PIN Bypass case handled for EMV Flow
-Online PIN Stuck Error Fixed
-add forceICCTermCurrencyCode flag into getCard
| 02.04.2026 | v7.4.53 | |
*For detailed version information, you can visit the page below.*
{% content-ref url="/pages/7DsCJTrSTv4GmNw07dTk" %}
[Platform Versions](/token-developer-portal-1/payment-service/versions/platform-versions.md)
{% endcontent-ref %}
[^1]:
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.tokeninc.com/token-developer-portal-1/payment-service/payment-services/card-service.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.