Bank App Protocol

Revision History

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

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.

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

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.

Ex: Request Sale Protocol Data

STX 01 E 1 002 000000125 1 000000001 000001 1 ABC123456789 141213 32 4E002542353430303633373530303031323938385E4B5552542F5A4552414E202020202020202020202020202020205E3135303232303131313031303030303030303030303035333330303030303F20000000000000000000000000A02808000000000038490340A028080020E5084002000000000000009FB504009FB50400000024003B353430303633373530303031323938383D313530323230313533333030313130313F346490FFBE0010C4400892FFBE90B50400B82708002B0000001E000000F815C44000000000844FBD40010000002B00000000000240A04FBD4000000000786BB84000000000FFFFFFFF0B00000091B5040000000000020000000400000000000000000000000A000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000064000000000002401A0000008A2F0500F815C440010000000000000000040000946AB8407C3105008A2F050001000000010000000820C440000000005391FFBE7C06B6400100000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 TRY 000000125 000341234 50 ETX

Response Sale APDU data

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

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

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

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

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

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

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

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

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

Ex: Request POS TXN Protocol Data

STX 03 E 1 003 64 ETX

Response POS Txn APDU Data

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

Ex: Request POS Settings Protocol Data

STX 04 E 1 006 68 ETX

Response POS Settings APDU DATA

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

Ex: Request Batch Close Protocol Data

STX 04 E 1 009 68 ETX

Response Batch Close APDU Data

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

Ex: Request Parameter Protocol Data

STX 04 E 1 010 68 ETX

Response Parameter APDU Data

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

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

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

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

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<dataLen;i++)
            chk += data[i];
     
      chk %= 100;
     
      return chk;
}

3 LIB APIS

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

This api is used to check whether the bank app support Dovis Pos to list bank app when the Sale is to be completed with Doviz.

Prototype:

unsigned short GetDovizPosSupport(unsigned char rfu);

Return Value:

0 : Supported.

-1, 1 : Not Supported.

PreviousOKC Linux Platform Next220TR/L

Last updated 11 hours ago