# Bank App Protocol ## Revision History | VERSION | AUTHOR | CHANGE | DATE | | ------- | ---------------- | ---------------------------------------- | ---------- | | 1.0 | Erdem ASLAN | First Release | 30.06.2013 | | 1.1 | Erdem ASLAN | | 16.08.2013 | | 1.2 | Erdem ASLAN | | 08.10.2013 | | 1.3 | Erdem ASLAN | | 08.11.2013 | | 2.0 | Erdem ASLAN | Merging Fiscal Receipt and Customer Slip | 18.12.2013 | | 3.0 | Erdem ASLAN | Common POS (Select Bank with Card PAN) | 20.06.2014 | | 3.1 | Erdem ASLAN | Aggrement on power loss. | 15.07.2014 | | 3.2 | Erdem ASLAN | Online Discount and Partial Limit | 31.08.2016 | | 3.3 | Erdem ASLAN | Food Sale | 29.09.2016 | | 3.4 | Erdem ASLAN | Coupon Sale | 06.10.2016 | | 3.5 | Erdem ASLAN | Protocol Version added. | | | 3.6 | Erdem ASLAN | Setup Funct. - LIB API set | 18.04.2017 | | 3.7 | Erdem ASLAN | LastSale protocol update | 16.05.2017 | | 3.8 | Erdem ASLAN | AID card route API | 24.08.2021 | | 4.0 | Ömer Alp Kolaylı | Currency Sale | 05.07.2024 | | 4.1 | Ömer Alp Kolaylı | Supported Currencies List | 23.12.2024 | | | | | | | | | | | ## 1 Description This document describes the communication protocol and functions between Fiscal APP, Bank APPs and Loyalty Apps. ## 2 Protocol Requirements ### *2.1* Protocol Fields **PDU**

[0]

[1]

[2]

[3]

[4]….[N-3]

[N-2]

[N-1]

[N]

STX

VER

VER

IDENT

A-PDU

CHKSUM

CHKSUM

ETX

**STX**:0x02 **VER**: 2 bytes ASCII. Protocol version. “A2” is the version that corresponds to Doc Version 4.0. **IDENT**: 1 byte ASCII. It is the identification of the App. RFU. **CHKSUM**: 2 bytes ASCII between ‘00’ – ‘99’. It contains the checksum calculation The A-PDU data format is below. |

HDR1

|

HDR2

|

HDR2

|

HDR2

|

DATA

| | --------------------------- | --------------------------- | --------------------------- | --------------------------- | --------------------------- | **Header1**: 1 byte ASCII. It is between ‘1’ and ‘9’, specifies the group of function. **Header2**: 3 bytes ASCII. It is between ‘001’ and ‘999’, specifies the activated function. Ever present into the argument A-PDU both in request than in replay, the answer reports the same number of the request. **DATA**: Data in ASCII format. // Protocol Header1 Paramaters \#define CMD\_HEADER1 '1' // Protocol Header2 Paramaters // H1 = 1 \#define CMD\_HELLO ‘001’ \#define CMD\_SALE ‘002’ // For all types of the Sale \#define CMD\_POS\_TXN ‘003’ // For Void,Batch and Parameter \#define CMD\_VOID ‘004’ // Directly Void Txn \#define CMD\_SLIP ‘005’ // For print slip \#define CMD\_SETTINGS ‘006’ // For service menu \#define CMD\_KEY\_INJECT ‘007’ // Reserved for use \#define CMD\_KEY\_CHECK ‘008’ // Reserved for use \#define CMD\_BATCH\_CLOSE ‘009’ // For request batch close \#define CMD\_PARAMETER ‘010’ // For request parameter \#define CMD\_SW\_UPDATE ‘011’ // Reserved for use \#define CMD\_LAST\_SALE ‘012’ // Last Sale \#define CMD\_RUN\_APP ‘013’ // Run app on start-up, rfu \#define CMD\_SETUP ‘014’ // Remote setup \#define CMD\_FOOD\_SALE ‘015’ // Food sale \#define CMD\_CPN\_SALE ‘016’ // Coupon sale \#define CMD\_CPN\_REQ\_POINT ‘017’ //Money Point request ### *2.2* Protocol Functions #### **2.2.1 Request Sale** This command is for all types of the Credit Card payments. ECR calls this function on Credit Card button clicked on Sale payment. **Request Sale APDU data** | Header 1 | ASCII | 1 | | ---------------------- | ----- | --- | | Header 2 | ASCII | 3 | | Amount | ASCII | 9 | | isFirstReq | ASCII | 1 | | ZNo | ASCII | 9 | | ReceiptNo | ASCII | 6 | | isInvoice | ASCII | 1 | | InvoiceNo | ASCII | 12 | | InvoiceDate | ASCII | 6 | | CardReadType | ASCII | 1 | | CardData | BIN | 512 | | CurrencyCode | ASCII | 3 | | Currency Amount | ASCII | 9 | | Currency Exchange Rate | ASCII | 9 | | Currency unit | ASCII | 6 | ***Amount**:* Sale amount. 2 bytes decimal. Ex:1.25 is written 000000125 ***isFirstReq**:* Reserved for use ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number ***isInvoice**:* to know whether Invoice data is existed ***InvoiceNo**:* Invoice number max 12 ASCII characters. ***InvoiceDate**:* Date of Invoice (DDMMYY) ***CardReadType**:* Type of the card reading. ``` enum CardReadType { NONE=0, ICC=1, MSR=2, ICC2MSR=3, KeyIn=4, CLCard=5, //Contactless cards, RFU }; ``` ***CardData**:* *-*If card read type is NONE, Bank is selected from Active Bank List. Bank App should read card itself. *-*If card read type is ICC, all of the CardData is set to 0x00. -If card read type is MSR or ICC2MSR, CardData is set to Track Data. Unsigned short usTk1Len; //2 Bytes unsigned char baTk1Buf\[128]; unsigned short usTk2Len; //2 Bytes unsigned char baTk2Buf\[128]; unsigned short usTk3Len; //2 Bytes unsigned char baTk3Buf\[128]; -If card read type is KeyIn, CardData is set to PAN data. ***CurrencyCode**:* Currency Code for Sale (TRY, USD, EUR, RUB, GBP, JPY) ***CurrencyAmount**:* Sale amount. 2 bytes decimal. Ex:1.25 is written 000000125 ***Currency Exchange Rate**:* Exchange Rate for currency. 4 bytes decimal. Ex: 1USD = 34,1234 is written as 000341234. ***Currency Unit:*** This data is from MB currency Table and defines the unit scale for a particular currency used in exchange rate calculations. It specifies whether the exchange rate is based on 1 unit of the currency (like USD or EUR) or 100 units (like JPY). Ex: Currency Unit * If the Currency Unit for JPY is 100, and the Currency Exchange Rate is 21.1234 TL for JPY, it means 100 JPY = 21.1234 TL. * • If the Currency Unit for USD is 1, and the Currency Exchange Rate is 35.1234 TL for USD, it means 1 USD = 35.1234 TL. **Ex**: Request Sale Protocol Data STX 01 E 1 002 000000125 1 000000001 000001 1 ABC123456789 141213 32 4E002542353430303633373530303031323938385E4B5552542F5A4552414E202020202020202020202020202020205E3135303232303131313031303030303030303030303035333330303030303F20000000000000000000000000A02808000000000038490340A028080020E5084002000000000000009FB504009FB50400000024003B353430303633373530303031323938383D313530323230313533333030313130313F346490FFBE0010C4400892FFBE90B50400B82708002B0000001E000000F815C44000000000844FBD40010000002B00000000000240A04FBD4000000000786BB84000000000FFFFFFFF0B00000091B5040000000000020000000400000000000000000000000A000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000064000000000002401A0000008A2F0500F815C440010000000000000000040000946AB8407C3105008A2F050001000000010000000820C440000000005391FFBE7C06B6400100000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 TRY 000000125 000341234 000100 50 ETX **Response Sale APDU data** | Description | Type | Length | | -------------- | ----- | ------ | | Header 1 | ASCII | 1 | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | | Payment Status | ASCII | 1 | | Amount | ASCII | 9 | | isSlip | ASCII | 1 | | Batch No | ASCII | 4 | | Txn No | ASCII | 6 | | Amount2 | ASCII | 9 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` ***Payment Status***: If discount or surcharge applied by Bank, return status according to enum SALE\_STATUS. ``` enum SALE_STATUS{ NORMAL=0, DISCOUNTED=1, SURCHARGEED=2(RFU) }; ``` ***Amount**:* Amount of the Sale that Banking Application charged. If Amount is less than Entered Amount by ECR it means Sale is Partial (Partial Limit). ***isSlip**:* If any Slip exists, return slip type according to enum SLIP\_TYPE ``` enum SLIP_TYPE{ NO_SLIP=0, MERCHANT_SLIP=1, CARDHOLDER_SLIP=2, BOTH_SLIPS=3, }; ``` ***Batch No**:* It is the current Batch No which includes current sale. ***Transaction No**:* It is the current Txn No of the sale in current Batch. ***Amount2**:* Amount of the discount. If app makes a discount set this value and add to message. **Ex**: Response Sale Protocol Data **Normal Sale** STX 01 B 1 002 00 0 000010000 0 0 0001 000001 40 ETX **Discounted Sale** (Entered Amount = 1000, Amount = 900, Discounted Amount = 100) STX 08 B 1 002 00 1 000000900 0 0 0001 000001 000000100 21 ETX **2.2.2 Request Food Sale** This command is for payment of the Food application. Request Food Sale APDU data | Header 1 | ASCII | 1 | | | ------------------------------------ | ------------------------ | ---------------- | ----------------------- | | Header 2 | ASCII | 3 | | | Amount | ASCII | 9 | | | ZNo | ASCII | 9 | | | ReceiptNo | ASCII | 6 | | |

8xVat Rate
Loan Amount

|

ASCII

ASCII

|

4

9

|

| ***Amount**:* Sale amount. 2 bytes decimal. Ex: 1.25 is written 000000125 ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number ***Vat Rate**:* ***Loan Amount:*** Loan for that Vat **Ex**: Request Food Sale Protocol Data STX E1015000000000000000125000007180000000100008000000020000100000003000000000 0000000000000000000000000000000000000000000000000000000000049 ETX **Response Food Sale APDU data** | Header 1 |

ASCII

|

1

| | ----------------------------- | -------------------- | ----------------- | |

Header 2

|

ASCII

|

3

| |

Response Code

|

ASCII

|

2

| |

Payment Status

|

ASCII

|

1

| |

Amount

|

ASCII

|

9

| |

isSlip

|

ASCII

|

1

| |

Batch No

|

ASCII

|

4

| |

Txn No

|

ASCII

|

6

| |

Amount2

|

ASCII

|

9

| |

Operator ID

|

ASCII

|

4

| |

PayType

|

ASCII

|

2

| |

Vat Rate

|

ASCII

|

4

| ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` ***Payment Status***: If discount or surcharge applied by Bank, return status according to enum SALE\_STATUS. ``` enum SALE_STATUS{ NORMAL=0, DISCOUNTED=1, SURCHARGEED=2(RFU) }; ``` ***Amount**:* Amount of the Sale that application charged. If Amount is less than Entered Amount by ECR it means Sale is Partial (Partial Limit). ***isSlip**:* If any Slip exists, return slip type according to enum SLIP\_TYPE **enum SLIP\_TYPE{** **NO\_SLIP=0,** **MERCHANT\_SLIP=1,** **CARDHOLDER\_SLIP=2,** **BOTH\_SLIPS=3,** **};** ***Batch No:*** It is the current Batch No which includes current sale. ***Transaction No**:* It is the current Txn No of the sale in current Batch. ***Amount2**:* Amount of the discount. If app makes a discount set this value and add to message. ***Operator ID**:* Payment operator ID. ***PayType**:* Payment type. ``` enum PAYMENT_TYPE { PAY_TYPE_FOOD=1, PAY_TYPE_COUPON=2, }; ``` ***Vat Rate**:* Paid Vat rate. **Ex**: Response Food Sale Protocol Data STX B1 015 00 0 000001000 1 0015 000002 000000000 1001 03 0800 37 ETX **2.2.3 Request Coupon Sale** This command is for payment of the Coupon application. Request Coupon Sale APDU data |

Header 1

|

ASCII

|

1

| | ----------------------- | -------------------- | ---------------- | | Header 2 | ASCII | 3 | | Amount | ASCII | 9 | | ZNo | ASCII | 9 | | ReceiptNo | ASCII | 6 | ***Amount**:* Sale amount. 2 bytes decimal. Ex: 1.25 is written 000000125 ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number **Ex**: Request Coupon Sale Protocol Data STX 01 E 1 016 000001000 000000131 000014 29 ETX **Response Coupon Sale APDU data** | Header 1 | ASCII | 1 | | -------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | | Payment Status | ASCII | 1 | | Amount | ASCII | 9 | | isSlip | ASCII | 1 | | Batch No | ASCII | 4 | | Txn No | ASCII | 6 | | Amount2 | ASCII | 9 | | Operator ID | ASCII | 4 | | PayType | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` ***Payment Status***: If discount or surcharge applied by Bank, return status according to enum SALE\_STATUS. ``` enum SALE_STATUS{ NORMAL=0, DISCOUNTED=1, SURCHARGEED=2(RFU) }; ``` ***Amount**:* Amount of the Sale that application charged. If Amount is less than Entered Amount by ECR it means Sale is Partial (Partial Limit). ***isSlip**:* If any Slip exists, return slip type according to enum SLIP\_TYPE ``` enum SLIP_TYPE{ NO_SLIP=0, MERCHANT_SLIP=1, CARDHOLDER_SLIP=2, BOTH_SLIPS=3, }; ``` ***Batch No:*** It is the current Batch No which includes current sale. ***Transaction No:*** It is the current Txn No of the sale in current Batch. ***Amount2**:* Amount of the discount. If app makes a discount set this value and add to message. **Ex**: Response Coupon Sale Protocol Data STX 01 B 1 016 00 0 000001000 1 0015 000002 000000000 1002 03 03 ETX ***Operator ID**:* Payment operator ID. ***PayType**:* Payment type. ``` enum PAYMENT_TYPE { PAY_TYPE_FOOD=1, PAY_TYPE_COUPON=2, }; ``` #### **2.2.4 Request Money Point** Request Money Point APDU Data |

Header 1

|

ASCII

|

1

| | ------------------------- | --------------------- | ------------------------- | |

Header 2

|

ASCII

|

3

| |

Amount

|

ASCII

|

9

| |

ZNo

|

ASCII

|

9

| |

ReceiptNo

|

ASCII

|

6

| |

CardID Len

|

ASCII

|

2

| |

CardID

|

ASCII

|

CardID Len

| ***Amount**:* Sale amount. 2 bytes decimal. Ex: 1.25 is written 000000125 ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number. ***CardID Len**:* Length of the Card ID. ***CardID**:* PAN of the card. **Ex**: Request Money Point Protocol Data STX 07 E 1 017 000000100 000000132 000010 16 1234567890123456 70 ETX **Response Slip APDU Data** |

Header 1

|

ASCII

|

1

| | ---------------------------- | -------------------- | ----------------- | |

Header 2

|

ASCII

|

3

| |

Response Code

|

ASCII

|

2

| |

isSlip

|

ASCII

|

1

| ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` ***isSlip**:* If any Slip exists, return slip type according to enum SLIP\_TYPE ``` enum SLIP_TYPE{ NO_SLIP=0, MERCHANT_SLIP=1, CARDHOLDER_SLIP=2, BOTH_SLIPS=3, }; ``` **Ex**: Response Money Point Protocol Data STX 06 B 1 017 00 2 15 ETX #### **2.2.5 Request Slip** This command is used for getting Slip after ECR finishes the Fiscal Receipt. ECR calls this command if any slip exists. Bank App should print all of the slips of Sale according to Zno and Receipt No. **Request Slip APDU Data** |

Header 1

|

ASCII

|

1

| | ------------------------ | --------------------- | ----------------- | |

Header 2

|

ASCII

|

3

| |

ZNo

|

ASCII

|

9

| |

ReceiptNo

|

ASCII

|

6

| |

SlipType

|

ASCII

|

1

| ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number ***SlipType**:* requested slip type. ``` enum SLIP_TYPE{ NO_SLIP=0, MERCHANT_SLIP=1, CARDHOLDER_SLIP=2, BOTH_SLIPS=3, }; ``` **Ex**: Request Slip Protocol Data STX 02 E 1 005 000000001 000001 1 65 ETX **Response Slip APDU Data** | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` **Ex**: Response Slip Protocol Data STX 02 B 1 005 00 58 ETX #### **2.2.6 Request Pos Transactions** This command is used for Pos transactions which is not relevant with a Fiscal Receipt( Batch Close, Void, Refund, Slip Repeat vs.). ECR calls it, if “Pos İşlemleri” item clicked on “Ana Menü” screen.This transactions can print slips if they needed. **Request POS Txn APDU Data** | Header 1 | ASCII | 1 | | -------- | ----- | - | | Header 2 | ASCII | 3 | **Ex**: Request POS TXN Protocol Data STX 03 E 1 003 64 ETX **Response POS Txn APDU Data** | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` **Ex**: Response POS TXN Protocol Data STX 03 E 1 003 64 ETX **2.2.7 Request Pos Settings** This Command is used for pos terminal settings. ECR calls it, if “Banka Kurulum” item clicked on “Servis İşlemleri” screen. **Request POS Settings APDU Data** | Header 1 | ASCII |

1

| | -------- | ----- | ---------------- | | Header 2 | ASCII | 3 | **Ex**: Request POS Settings Protocol Data STX 04 E 1 006 68 ETX **Response POS Settings APDU DATA** | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` **Ex**: Response POS Settings Protocol Data STX 04 B 1 006 00 61 ETX #### **2.2.8 Request Batch Close** This Command is used for request batch close. ECR calls it in a service, which set by tms actions. **Request Batch Close APDU Data** | Header 1 | ASCII | 1 | | -------- | ----- | - | | Header 2 | ASCII | 3 | **Ex**: Request Batch Close Protocol Data STX 04 E 1 009 68 ETX **Response Batch Close APDU Data** | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request.enum TXN\_RET\_CODE{ ``` RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` Ex: Response Batch Close Protocol Data STX 04 B 1 009 00 61 ETX #### **2.2.9 Request Parameter** This Command is used for request parameter. ECR calls it in a service, which set by tms actions. **Request Parameter APDU Data** | Header 1 | ASCII | 1 | | -------- | ----- | - | | Header 2 | ASCII | 3 | **Ex**: Request Parameter Protocol Data STX 04 E 1 010 68 ETX Response Parameter APDU Data | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` **Ex**: Response Parameter Protocol Data STX 04 B 1 010 00 61 ETX **NOTE**: enum TXN\_RET\_CODE is temporarily. It will be edit with necessary codes according to feedbacks. **2.2.10 Request Last Sale Data** This command used for getting data of the Last Sale. If any power loss occurred on Sale operation, ECR request data of the Last Sale after starting. For detailed info please see PrSp\_Mali\_İşlem\_İşAkışı.doc . **Request Last Sale Data APDU Data** |

Header 1

|

ASCII

|

1

| | ------------------------ | --------------------- | ---------------- | |

Header 2

|

ASCII

|

3

| |

ZNo

|

ASCII

|

9

| |

ReceiptNo

|

ASCII

|

6

| ***ZNo**:* Z number of the current receipt /sale. ***ReceiptNo***: Receipt number . **Ex**: Request Last Sale Protocol Data STX 04 E 1 010 000000001 000005 68 ETX **Response LastSale Data APDU Data** |

Header 1

|

ASCII

|

1

| | ----------------------------- | -------------------- | ----------------- | |

Header 2

|

ASCII

|

3

| |

Response Code

|

ASCII

|

2

| |

Payment Status

|

ASCII

|

1

| |

Amount

|

ASCII

|

9

| |

Batch No

|

ASCII

|

4

| |

Txn No

|

ASCII

|

6

| |

Amount2

|

ASCII

|

9

| |

Operator ID

|

ASCII

|

4

| |

PayType

|

ASCII

|

2

| |

Vat Rate

|

ASCII

|

4

| ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` ***Payment Status***: If discount or surcharge applied by Bank, return status according to enum SALE\_STATUS. ``` enum SALE_STATUS{ NORMAL=0, DISCOUNTED=1, SURCHARGEED=2(RFU) }; ``` ***Amount**:* Amount of the requested sale . ***Batch No**:* Current Batch No which includes requested sale. ***Transaction No**:* Current Txn No of the requested sale in Batch. ***Amount2**:* Amount of the discount. If app makes a discount set this value and add to message. ***Operator ID**:* Payment operator ID. ***PayType**:* Payment type. ``` enum PAYMENT_TYPE { PAY_TYPE_FOOD=1, PAY_TYPE_COUPON=2, }; ``` ***Vat Rate**:* Paid Vat rate. **Ex**: Response Last Sale Protocol Data STX 05 B 1 010 00 1 000000100 0001 000001 000000100 0000 00 0000 65 ETX #### **2.2.11 Request Setup** This command used for remote setup. After remote setup Bank app should print a slip to inform merchant about the status of the terminal. **Request Setup APDU Data** |

Header 1

|

ASCII

|

1

| | -------------------------- | --------------------- | ----------------- | |

Header 2

|

ASCII

|

3

| |

Merchant ID

|

ASCII

|

32

| |

Terminal ID

|

ASCII

|

32

| ***Merchant ID**:* App merchant ID. Left justified, willed with ‘0’ ***Terminal ID**:* App tertminal ID.Left justified, filled with ‘0’ **Ex**: Request Setup Protocol Data STX 04 E 1 014 12345678900000000000000000000000 12345678900000000000000000000000 68 ETX **Response Setup APDU Data** | Header 1 | ASCII | 1 | | ------------- | ----- | - | | Header 2 | ASCII | 3 | | Response Code | ASCII | 2 | ***Response Code**:* Return of the request. ``` enum TXN_RET_CODE{ RET_SUCCESS=0, RET_ERROR=1, RET_CANCELLED=2, RET_OFFLINE_DECLINE=3, RET_UNABLE_DECLINE=4, RET_ONLINE_DECLINE=5, }; ``` **Ex**: Response Parameter Protocol Data STX 04 B 1 014 00 65 ETX ### *2.3* Helper Functions #### **2.3.1 CheckSum Function** ``` int checkSum(unsigned char *data, int dataLen) { int chk=0; int i=0; for(i=0;i ECR needs special information for some functionalities. Payment App develeopers should develop some APIs to support. ### *3.1* GetCardTypeList This api is used to check the type (Issuer, Brand, Not Onus, None) of the card for the Bank. This data is used to run proper bank app. Please see *PrSp\_Otomatik\_Banka\_Yonlendirme.doc*. **Prototype**: ``` unsigned short GetCardTypeList(unsigned char readType, unsigned char *PAN, unsigned char PANLen, BIN_DATA_t* binData); ``` **Input Parameters:** ***readType**:* The method of the card read. \#define READ\_TYPE\_ICC 0x01 \#define READ\_TYPE\_MSR 0x02 \#define READ\_TYPE\_ICC2MSR 0x03 \#define READ\_TYPE\_KEYIN 0x04 \#define READ\_TYPE\_CLESS 0x05 ***PAN**:* card number. ***PANLen**:* length of the card number. **Output Parameters:** ***binData**:* Current Txn No of the requested sale in Batch. ``` typedef struct { char bankAppName[25]; //The name of the CAP start with BNK_ char bankName[50]; // ? //Official Bank Name in the field unsigned char cardType; } BIN_DATA_t; ``` \#define CARD\_TYPE\_NONE 0x01 \#define CARD\_TYPE\_NOT\_ONUS 0x02 \#define CARD\_TYPE\_ISSUER 0x03 \#define CARD\_TYPE\_BRAND 0x04 **Return Value:** 0 : Success. -1, 1 : Error **NOTE**: You can store a file in “home/ap/pub/APPNAME” folder to get the TerminalID and MerchantID. For Ex: /home/ap/pub/BNK\_000\_TEMPL ### *3.2* GetCLessSupport This api is used to check whether the bank app support Contactless interface. **Prototype**: ``` unsigned short GetCLessSupport(unsigned char *isContatcless); ``` **Output Parameters:** ***isContactless**:* TRUE if contactless supported, FALSE if not. Return Value: 0 : Success. -1, 1 : Error ### *3.3* GetSetupParameters This api is used to check the set terminal on the Payment App. **Prototype**: ``` unsigned short GetSetupParameters(unsigned char *merchantID, unsigned char *terminalID); ``` **Output Parameters:** ***merchantID**:* ASCI data. ***terminalID**:* ASCI data. **Return Value:** 0 : Success. -1, 1 : Error. **NOTE**: You can store a file in “home/ap/pub/APPNAME” folder to get the TerminalID and MerchantID. For Ex: /home/ap/pub/BNK\_000\_TEMPL. ### *3.4* GetSupportedAIDList This api used to get supported AID list of banks. **Prototype**: ``` unsigned short GetSupportedAIDList(unsigned char cardReadType, unsigned char *AID, char AIDList [32][17]); ``` **Input Parameters:** ***cardReadType**:* The method of the card read.rfu. ***AID**:* AID of the card. **Output Parameters:** *AIDList:* List of the supported AIDs. **Return Value:** 0 : not supported. 1 : supported. ### *3.5* GetDovizPosSupport NOTE: This API is deprecated but still supported. However, it is recommended to use the **GetSupportedCurrencies** API, as it should be used for listing according to the supported currency types. This API checks if the bank app supports Doviz POS, enabling the bank app to be listed during the Sale completion process with foreign currency. **Prototype**: ``` unsigned short GetDovizPosSupport(unsigned char rfu); ``` **Return Value:** 0 : Supported. -1, 1 : Not Supported. ### 3.6 GetSupportedCurrencies This api used to get supported Currencies list of banks. Supported Devices: 300TR Prototype: unsigned short GetSupportedCurrencies(char supportedCurrencies \[20]\[17]); Input Parameters: Output Parameters: *supportedCurrencies:* List of the supported currencies. Return Value: Currencies count: Count of supported currencies. If not support Doviz Pos return value must be 0.