EMV API: Difference between revisions

Latest revision as of 07:29, 19 November 2018

Card Reader

Open reader and wait card

int open_reader(int reader)

Open the card reader of the POS. If select open all of readers, any open success return success.

Parameters
reader	int: 0: all of readers,1: only contact reader,2: only contactless reader.

Returns
int	The result code, >= 0, success; <0 error code.

Close reader

void close_reader(int reader)

Close the card reader of the POS.

Parameters
reader	int: 0: all of readers,1: only contact reader,2: only contactless reader.

Get current card type

int get_card_type(void)

Returns
int	The result , 1:contact card; 2:contactless card; -1: no card.

Get card ATR

int get_card_atr(unsigned char *pATR)

Parameters
pATR	*unsigned char :** the value of ATR.

Returns
int	The result code, >= 0, the length of ATR; <0 error code.

APDU command

int transmit_card( unsigned char *cmd,int cmdLength,unsigned char *respData,int respDataLength)

Parameters
cmd	*unsigned char :** APDU command.
cmdLength	int: the length of APDU command.
respData	*unsigned char :** the value of card response.
respDataLength	int: accepted max length of card reasponse.

Returns
int	The result code, >=0,the length of card response; <0 error code.

Store and set EMV data

Check the existence of data for the tag

int emv_is_tag_present(int tag)

Parameters
tag	int: tag name.

Returns
int	The result code, >= 0, the length of data; <0 the data not exist.

Get the data for the tag

int emv_get_tag_data(int tag, unsigned char *data, int dataLength)

Parameters
tag	int: tag name.
data	*unsigned char :** the value of the data.
int	int: accepted max length of the data.

Returns
int	The result code, >= 0, the length of the data; <0 error code.

Get the data for the tag list

int emv_get_tag_list_data(int *tagNames, int tagCount,unsigned char *pTagsValue,int pTagsValueLength)

Parameters
tagNames	*int :** the list of the tags.
tagCount	int: the count of the tags.
pTagsValue	*unsigned char :** the values of the data（TLV format）.
pTagsValueLength	int: accepted max length of the data.

Returns
int	The result code, >= 0, the length of the data; <0 error code.

Set the data for the tag

int emv_set_tag_data(int tag, unsigned char *data, int length)

Parameters
tag	int: tag name.
data	*unsigned char :** the value of the data.
length	int: the length of the data.

Returns
int	The result code, >= 0, the length of the data; <0 error code.

EMV transaction processing

EMVKernel initialize

void emv_kernel_initialize(unsigned char *pInitData)

Parameters
pInitData	*unsigned char :** See from follows

typedef struct
{
// callback function for card event
CARD_EVENT_OCCURED pCafdEventOccured;
// callback function for EVM processing
EMV_PROCESS_CALLBACK pEVMProcessCallback;
}EMV_INIT_DATA;

1） typedef void (*CARD_EVENT_OCCURED) (int eventType)
// any card event occured, this function will be revoked
// @param[in] eventType : SMART_CARD_EVENT_INSERT_CARD = 0;
// : SMART_CARD_EVENT_REMOVE_CARD = 1;
// : SMART_CARD_EVENT_POWERON_ERROR = 9;
// :SMART_CARD_EVENT_CONTALESS_HAVE_MORE_CARD = 10;
2） typedef void (*EMV_PROCESS_CALLBACK)(unsigned char *pData);
// callback function for EVM processing， pData have 2 bytes
// unsigned char status = pData[0]；
// unsigned char desc = pData[1]；
* status：
* STATUS_ERROR = 0; //ERROR
* STATUS_CONTINUE = 1; // not completed, need to continue
* STATUS_COMPLETION = 2; // completed
* desc
* when status = STATUS_COMPLETION， desc means：
* APPROVE_OFFLINE = 1; //Transaction approved Offline
* APPROVE_ONLINE = 2; //Transaction approved Online
* DECLINE_OFFLINE = 3; //Transaction declined Offline
* DECLINE_ONLINE = 4; //Transaction declined Onlin
* *
when status = STATUS_ERROR， desc means：
* SUCCESS = 0; //SUCCESS
* ERROR_NO_APP = 1; //No Application Selected when Application Select
* ERROR_APP_BLOCKED = 2; //card return 6A81 when Application Select
* ERROR_APP_SELECT = 3; //Error when Application Select
* ERROR_INIT_APP = 4; //Error when Initialize Application Data
* ERROR_EXPIRED_CARD = 5; // Card Expired
* ERROR_APP_DATA = 6; //Error when Read Application Data
* ERROR_DATA_INVALID = 7; // have invalid data
* ERROR_DATA_AUTH = 8; // Fail in offline authentication
* ERROR_GEN_AC = 9; //Generate AC error when Transaction Process
* ERROR_PROCESS_CMD = 10; //Process Command ERROR
* ERROR_SERVICE_NOT_ALLOWED = 11; //Service not Allowed
* ERROR_PINENTERY_TIMEOUT = 12; //PIN Entry timeout
* ERROR_OFFLINE_VERIFY = 13; //Check Offline PIN Error when Cardholder Verify
* ERROR_NEED_ADVICE = 14; //Communication Error with Host, but the card need
advice, halted the transaction
* ERROR_USER_CANCELLED = 15;
* ERROR_AMOUNT_OVER_LIMIT = 16; // amount over limit
* ERROR_AMOUNT_ZERO = 17; // amount can not be zero
* ERROR_OTHER_CARD = 18； // Please try other card
* *
when status = STATUS_CONTINUE， desc means：
* EMV_CANDIDATE_LIST = 1; //notify Application show Application Candidate List
* EMV_APP_SELECTED = 2; //Application Select Completed
* EMV_READ_APP_DATA = 3; //Read Application Data Completed
* EMV_DATA_AUTH = 4; //Data Authentication Completed
* EMV_OFFLINE_PIN = 5; // notify Application prompt Caldholder enter offline PIN,
* EMV_ONLINE_ENC_PIN = 6; //notify Application prompt Caldholder enter Online
PIN
* EMV_PIN_BYPASS_CONFIRM = 7; //notify Application confirm to Accepted PIN
Bypass or not
* EMV_PROCESS_ONLINE = 8; //notify Application to Process Online
* EMV_ID_CHECK = 9; //notify Application Check Cardholder's Identification
*/

Initialize EMV transaction data

void emv_trans_initialize(void)

EMV processing function

int emv_process_next(void)

Returns
int	The result code, >= 0, success; <0 error code.

Others functions

Get EMV Kernel version

int emv_get_version_string(unsigned char *buffer, int bufferLength)

Parameters
buffer	*unsigned char :** the value of emv kernel version.
bufferLength	int: accepted max length of emv kernel version.

Returns
int	The result code, >= 0, the length of emv kernel verion; <0 error code.

Set transaction amount

int emv_set_trans_amount(unsigned char *amount)

Parameters
amount	*unsigned char :** '\0' as ending mark.

Returns
int	The result code, >= 0, success; <0 error code.

Set other amount

int emv_set_other_amount(unsigned char *amount)

Parameters
amount	*unsigned char :** '\0' as ending mark.

Returns
int	The result code, >= 0, success; <0 error code.

Set transaction type

int emv_set_trans_type(unsigned char transType)

Parameters
transType	unsigned char: transaction type.

#define TRANS_GOODS_SERVICE 0x00
#define TRANS_CASH 0x01
#define TRANS_INQUIRY 0x04
#define TRANS_TRANSFER 0x05
#define TRANS_PAYMENT 0x06
#define TRANS_ADMIN 0x07
#define TRANS_CASHBACK 0x09
#define TRANS_CARD_RECORD 0x0A

Returns
int	The result code, >= 0, success; <0 error code.

Set emv kernel type

int emv_set_kernel_type(unsigned char kernelType)

Parameters
kernelType	unsigned char: kernel type, 1:EMV Contact Kernel; 2:EMV Contactless Kernel; 3:UPCASH Kernel for China Union Pay.

#define TRANS_GOODS_SERVICE 0x00
#define TRANS_CASH 0x01
#define TRANS_INQUIRY 0x04
#define TRANS_TRANSFER 0x05
#define TRANS_PAYMENT 0x06
#define TRANS_ADMIN 0x07
#define TRANS_CASHBACK 0x09
#define TRANS_CARD_RECORD 0x0A

Returns
int	The result code, >= 0, success; <0 error code.

Is needed advice the transaction

int emv_is_need_advice(void)

Returns
int	The result , = 1, need advice; =0 not need advice.

Is needed sign the transaction

int emv_is_need_signature(void)

Returns
int	The result , = 1, need sign; =0 not need sign.

Set the parameter for force online

int emv_set_force_online(int flag)

Parameters
flag	int: 1:Yes;0:No.

Returns
int	The result , = 1, force online; =0 not force online.

Read transaction record from the card

int emv_get_card_record(uint8_t *data, int dataLength)

Parameters
data	*uint8_t :** transaction record.
dataLength	int: accepted max length for the transaction record.

Returns
int	The result , >= 0, record count; <0 error code.

Get application list

int emv_get_candidate_list(uint8_t *data, int dataLength)

Parameters
data	*uint8_t :** application list as "LV" format.
dataLength	int: accepted max length for application list.

Returns
int	The result , >= 0, application count; <0 error code.

Set the selected index for application selection

int emv_set_candidate_list_result(int index)

Parameters
index	int: the selected index (started by 0).

Returns
int	The result , >= 0,success; <0 error code.

Set the result for cardholder ID check

int emv_set_id_check_result(int result)

Parameters
result	int: ID Type（9F62）、 ID Number(9F61) 0: check Fail， 1:check success.

Returns
int	The result , >= 0,success; <0 error code.

Set the result for Online PIN

int emv_set_online_pin_entered(int result)

Parameters
result	int: 0: Online PIN not input， 1:Online PIN inputted.

Returns
int	The result , >= 0,success; <0 error code.

Set acceptance for Bypass PIN

int emv_set_pin_bypass_confirmed(int result)

Parameters
result	int: 0: refused bypass pin， 1: accepted bypass pin.

Returns
int	The result , >= 0,success; <0 error code.

Set the result for online certification

int emv_set_online_result(int result,unsigned char *respCode,unsigned char *issuerRespData,int issuerRespDataLength)

Parameters
result	int: -1:communication failed； 0: host refused； 1: host accepted.
respCode	*unsigned char :** 2 bytes response code from the host.
issuerRespData	*unsigned char :** the emv data from the host.
issuerRespDataLength	int: the length of the emv data from the host.

Returns
int	The result , >= 0,success; <0 error code.

Get Kernel checksum

int emv_get_kernel_checksum(unsigned char *buffer, int bufferLength)

Parameters
buffer	*unsigned char :** the value of emv kernel checksum.
bufferLength	int: accepted max length.

Returns
int	The result , >= 0,the length of kernel checksum; <0 error code.

Get Configuration checksum

int emv_get_config_checksum(unsigned char *buffer, int bufferLength)

Parameters
buffer	*unsigned char :** the value of configuration checksum.
bufferLength	int: accepted max length.

Returns
int	The result , >= 0,the length of configuration checksum; <0 error code.

Setup EMVparameters

Clear AID info

int emv_aidparam_clear(void)

Returns
int	The result , >= 0,success; <0 error code.

Add AID info

int emv_aidparam_add( uint8_t *data, int dataLength)

Parameters
data	*uint8_t :** see form below， format is TLV.
dataLength	int: the length of the data.

Name	Format	Length(byte)	tag
AID	b	5－16	9F06
Application selection Indicator(ASI)	b	1	DF01
Application version number	b	2	9F08
TAC－Default	b	5	DF11
TAC－Online	b	5	DF12
TAC－Denial	b	5	DF13
Terminal floor limit	b	4	9F1B
Threshold value for Biased Random Selection	b	4	DF15
Maximum Target Percentage to be used for Biased Random Selection	b	1	DF16
Target Percentage to be used for Random Selection	b	1	DF17
Default DDOL	b	Var.	DF14
Ability for Online PIN	b	1	DF18
Application Label	b	1-16	50
Application Preferred Name	b	1-16	9F12
Application Priority Indicator	b	1	87
Merchant Identifier	b	15	9F16
Acquirer Identifier	b	6-11	9F01
MCC	b	4	9F15
POS Entry Mode	b	2	9F39
Transaction Reference Currency Code	b	3	9F3C
Transaction Reference Currency Exponent	b	1	9F3D
Default TDOL	b	Var.	DF22

Returns
int	The result code, >= 0, success; <0 error code.

Clear CAPK info

int emv_capkparam_clear(void)

Returns
int	The result code, >= 0, success; <0 error code.

Add CAPK info

int emv_capkparam_add( uint8_t *data, int dataLength)

Parameters
data	*uint8_t :** see form below， format is TLV.
dataLength	int: the length of the data.

Name	Format	Length(byte)	tag
RID	b	5	9F06
Certification Authority Public Key Index	b	1	9F22
Certification Authority Public Key Expiration Date	n8	8	DF05
Certification Authority Public Key hash Algorithm Indicator	b	1	DF06
Certification Authority Public Key Algorithm Indicator	b	1	DF07
Certification Authority Public Key Modulus	b	Var.	DF02
Certification Authority Public Key Exponent	b	1 or 3	DF04
Certification Authority Public Key Checksum	b	Var.	DF03

Returns
int	The result code, >= 0, success; <0 error code.

Set EMV terminal parameters

int emv_terminal_param_set( uint8_t *TerminalParam)

Parameters
TerminalParam	*uint8_t :** see form below.

typedef struct{
unsigned char terminal_country_code[2]; // 9F1A [BCD] : Terminal Country Code
unsigned char TID[8]; // 9F1C [ASC]
unsigned char IFD[8]; // 9F1E [ASC] : IFD Serial Number
unsigned char transaction_currency_code[2]; // 5F2A [BCD]
unsigned char terminal_capabilities[3]; // 9F33 [BIN]
unsigned char terminal_type[1]; // 9F35 [BCD]
unsigned char transaction_currency_exponent[1]; // 5F36 [BCD]
unsigned char additional_terminal_capabilities[5]; // 9F40 [BIN]
unsigned char merchantNameLength;
unsigned char merchantName[20]; // 9F4E [ASC]
unsigned char rev[2];
}TERMINAL_INFO;

Returns
int	The result code, >= 0, success; <0 error code.

Clear Exception File

int emv_exception_file_clear(void)

Returns
int	The result code, >= 0, success; <0 error code.

Add Exception File

int emv_exception_file_add( unsigned char *exceptFile)

Parameters
exceptFile	*unsigned char :** see form below.

Typedef struct{
unsigned char cardNo[19]; // PAN
unsigned char panSequence; // PAN Sequence Number
}ExceptionFile

Returns
int	The result code, >= 0, success; <0 error code.

Clear Revoked Certicates

int emv_revoked_cert_clear(void)

Returns
int	The result code, >= 0, success; <0 error code.

Add revoked Certificate

int emv_revoked_cert_add( uint8_t *revokedCert)

Parameters
revokedCert	*uint8_t :** see form below.

Typedef struct{
unsigned char rid[5];
unsigned char capki;
}RevokedCert

Returns
int	The result code, >= 0, success; <0 error code.