EMV API: Difference between revisions

From wizarPOS
No edit summary
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Card Reader==
== <big>Card Reader</big>==
The EMV.
=== <big>Open reader and wait card</big> ===
=== open reader and wait card ===
  <syntaxhighlight lang="java">int open_reader(int reader)</syntaxhighlight >
  int open_reader(int reader)
Open the card reader of the POS.
Open the card reader of the POS.
If select open all of readers, any open success return success.
If select open all of readers, any open success return success.
 
{|class="wizarpostable"
'''Parameters'''
|-
! scope="row" colspan="2" | Parameters
|-
| reader || '''int:''' 0: all of readers,1: only contact reader,2: only contactless reader.
|}
{|
{|
|-
|-
| ''reader'' || int || 0: all of readers,1: only contact reader,2: only contactless reader.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}


'''Returns'''
=== <big>Close reader</big> ===
 
   <syntaxhighlight lang="java">void close_reader(int reader)</syntaxhighlight >
The result code, >= 0, success; <0 [[Error_code|error code]].
=== close reader ===
   void close_reader(int reader)
Close the card reader of the POS.
Close the card reader of the POS.


'''Parameters'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
|-
| ''reader'' || int || 0: all of readers,1: only contact reader,2: only contactless reader.
| reader || '''int:''' 0: all of readers,1: only contact reader,2: only contactless reader.
|}
|}


'''Returns'''
=== <big>Get current card type</big> ===
  <syntaxhighlight lang="java">int get_card_type(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , 1:contact card; 2:contactless card; -1: no card.
|}


The result code, >= 0, success; <0 [[Error_code|error code]].
=== <big>Get card ATR</big> ===
  <syntaxhighlight lang="java">int get_card_atr(unsigned char *pATR)</syntaxhighlight >
=== get current card type ===
{|class="wizarpostable"
  int get_card_type(void)
|-
! scope="row" colspan="2" | Parameters
|-
| pATR || '''unsigned char *:''' the value of ATR.
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, the length of ATR; <0 [[Error_code|error code]].
|}


'''Parameters'''
===  <big>APDU command</big> ===
  <syntaxhighlight lang="java">int transmit_card( unsigned char *cmd,int cmdLength,unsigned char *respData,int respDataLength)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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.
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >=0,the length of card response; <0 [[Error_code|error code]].
|}


'''Returns'''


The result , 1:contact card; 2:contactless card; -1: no card.
== <big>Store and set EMV data</big> ==
=== <big>Check the existence of data for the tag</big> ===
=== get card ATR ===
   <syntaxhighlight lang="java">int emv_is_tag_present(int tag)</syntaxhighlight >
   int get_card_atr(unsigned char *pATR)
{|class="wizarpostable"
 
|-
'''Parameters'''
! scope="row" colspan="2" | Parameters
|-
| tag || '''int:''' tag name.
|}
{|
{|
|-
|-
| ''pATR'' || unsigned char * || the value of ATR.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, the length of data; <0 the data not exist.
|}
|}
'''Returns'''


The result code, >= 0, the length of ATR; <0 [[Error_code|error code]].


=== APDU command ===
=== <big>Get the data for the tag</big> ===
   int transmit_card( unsigned char *cmd,int cmdLength,unsigned char *respData,int respDataLength)
   <syntaxhighlight lang="java">int emv_get_tag_data(int tag, unsigned char *data, int dataLength)</syntaxhighlight >


'''Parameters'''
{|class="wizarpostable"
{|
|-
|-
| ''cmd'' || unsigned char * || APDU command.
! scope="row" colspan="2" | Parameters
|-
|-
| ''cmdLength'' || int || the length of APDU command.
| tag || '''int:''' tag name.
|-
|-
| ''respData'' || unsigned char * || the value of card response.
| data || '''unsigned char *:''' the value of the data.
|-
|-
| ''respDataLength'' || int|| accepted max length of card reasponse.
| int || '''int:''' accepted max length of the data.
|}
|}
'''Returns'''
The result code, >=0,the length of card response; <0 [[Error_code|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.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, the length of the data; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, the length of data; <0 the data not exist.


=== get the data for the tag ===
=== <big>Get the data for the tag list</big> ===
   int emv_get_tag_data(int tag, unsigned char *data, int dataLength)
   <syntaxhighlight lang="java">int emv_get_tag_list_data(int *tagNames, int tagCount,unsigned char *pTagsValue,int pTagsValueLength)</syntaxhighlight >


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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.
|}
{|
{|
|-
|-
| ''tag'' || int || tag name.
|  
|}
{|class="wizarpostable"
|-
|-
| ''data'' || unsigned char * || the value of the data.
!  scope="row" colspan="2" | Returns
|-
|-
| ''int'' || int || accepted max length of the data.
| int || The result code, >= 0, the length of the data; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, the length of the data; <0 [[Error_code|error code]].


=== get the data for the tag list ===
=== <big>Set the data for the tag</big> ===
   int emv_get_tag_list_data(int *tagNames, int tagCount,unsigned char *pTagsValue,int pTagsValueLength)
   <syntaxhighlight lang="java">int emv_set_tag_data(int tag, unsigned char *data, int length)</syntaxhighlight >


'''Parameters'''
{|class="wizarpostable"
{|
|-
|-
| ''tagNames'' || int *|| the list of the tags.
! scope="row" colspan="2" | Parameters
|-
|-
| ''tagCount'' || int || the count of the tags.
| tag || '''int:''' tag name.
|-
|-
| ''pTagsValue'' || unsigned char * || the values of the data（TLV format）.
| data || '''unsigned char *:''' the value of the data.
|-
|-
| ''pTagsValueLength'' || int || the count of the data.
| length || '''int:''' the length of the data.
|}
|}
'''Returns'''
The result code, >= 0, the length of the data; <0 [[Error_code|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.
|  
|}
{|class="wizarpostable"
|-
|-
| ''data'' || unsigned char *|| the value of the data.
!  scope="row" colspan="2" | Returns
|-
|-
| ''length'' || int || the length of the data.
| int || The result code, >= 0, the length of the data; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, the length of the data; <0 [[Error_code|error code]].


== EMV transaction processing ==
== <big>EMV transaction processing</big> ==
=== EMVKernel initialize ===
=== <big>EMVKernel initialize</big> ===
The snippet code is as follows:
  <syntaxhighlight lang="java">void emv_kernel_initialize(unsigned char *pInitData)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| pInitData || '''unsigned char *:''' See from follows
|}
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
typedef struct
typedef struct
Line 139: Line 198:
EMV_PROCESS_CALLBACK pEVMProcessCallback;
EMV_PROCESS_CALLBACK pEVMProcessCallback;
}EMV_INIT_DATA;
}EMV_INIT_DATA;
void emv_kernel_initialize(unsigned char *pInitData)
 
1） typedef void (*CARD_EVENT_OCCURED) (int eventType)
1） typedef void (*CARD_EVENT_OCCURED) (int eventType)
// any card event occured, this function will be revoked
// any card event occured, this function will be revoked
Line 197: Line 256:
*/
*/
</syntaxhighlight >
</syntaxhighlight >
=== Initialize EMV transaction data ===
  void emv_trans_initialize(void)
=== EMV processing function ===
  int emv_process_next(void)


'''Parameters'''


'''Returns'''
=== <big>Initialize EMV transaction data</big> ===
The result code, >= 0, success; <0 [[Error_code|error code]].
  <syntaxhighlight lang="java">void emv_trans_initialize(void)</syntaxhighlight >


== Others functions ==
=== Get EMV Kernel version ===
  int emv_get_version_string(unsigned char *buffer, int bufferLength)


'''Parameters'''
=== <big>EMV processing function</big> ===
  <syntaxhighlight lang="java">int emv_process_next(void)</syntaxhighlight >
{|
{|
|-
|-
| ''buffer'' || unsigned char * || the value of emv kernel version.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|-
| ''bufferLength'' || int || accepted max length of emv kernel version.
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, the length of emv kernel verion; <0 [[Error_code|error code]].


=== Set transaction amount ===
  int emv_set_trans_amount(unsigned char *amount)


'''Parameters'''
== <big>Others functions</big> ==
=== <big>Get EMV Kernel version</big> ===
  <syntaxhighlight lang="java">int emv_get_version_string(unsigned char *buffer, int bufferLength)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| buffer || '''unsigned char *:''' the value of emv kernel version.
|-
| bufferLength || '''int:''' accepted max length of emv kernel version.
|}
{|
{|
|-
|-
| ''amount'' || unsigned char * || '\0' as ending mark.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, the length of emv kernel verion; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].


=== Set other amount ===
  int emv_set_other_amount(unsigned char *amount)


'''Parameters'''
=== <big>Set transaction amount</big> ===
  <syntaxhighlight lang="java">int emv_set_trans_amount(unsigned char *amount)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| amount || '''unsigned char *:''' '\0' as ending mark.
|}
{|
{|
|-
|-
| ''amount'' || unsigned char * || '\0' as ending mark.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].


=== Set transaction type ===
  int emv_set_trans_type(unsigned char transType)


'''Parameters'''
=== <big>Set other amount</big> ===
  <syntaxhighlight lang="java">int emv_set_other_amount(unsigned char *amount)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| amount || '''unsigned char *:''' '\0' as ending mark.
|}
{|
{|
|-
|-
| ''transType'' || unsigned char || transaction type.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Set transaction type</big> ===
  <syntaxhighlight lang="java">int emv_set_trans_type(unsigned char transType)</syntaxhighlight >
 
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| transType|| '''unsigned char:''' transaction type.
|}
|}
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
Line 261: Line 358:
#define TRANS_CARD_RECORD 0x0A
#define TRANS_CARD_RECORD 0x0A
</syntaxhighlight >
</syntaxhighlight >
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}


'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].


=== set emv kernel type ===
=== <big>Set emv kernel type</big> ===
   int emv_set_kernel_type(unsigned char kernelType)
   <syntaxhighlight lang="java">int emv_set_kernel_type(unsigned char kernelType)</syntaxhighlight >
 
{|class="wizarpostable"
'''Parameters'''
|-
{|
! scope="row" colspan="2" | Parameters
|-
|-
| ''kernelType'' || unsigned char || kernel type, 1:EMV KERNAL; 2:QPBOC KERNAL for China; 3:UPCASH_KERNAL for China.
| kernelType || '''unsigned char:''' kernel type, 1:EMV Contact Kernel; 2:EMV Contactless Kernel; 3:UPCASH Kernel for China Union Pay.
|}
|}
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
Line 283: Line 388:
#define TRANS_CARD_RECORD 0x0A
#define TRANS_CARD_RECORD 0x0A
</syntaxhighlight >
</syntaxhighlight >
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}


'''Returns'''
=== <big>Is needed advice the transaction</big> ===
The result code, >= 0, success; <0 [[Error_code|error code]].
  <syntaxhighlight lang="java">int emv_is_need_advice(void)</syntaxhighlight >


=== Is needed advice the transaction ===
{|class="wizarpostable"
  int emv_is_need_advice(void)
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , = 1, need advice; =0 not need advice.
|}


'''Parameters'''


'''Returns'''
=== <big>Is needed sign the transaction</big> ===
The result , = 1, need advice; =0 not need advice.
  <syntaxhighlight lang="java">int emv_is_need_signature(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , = 1, need sign; =0 not need sign.
|}


=== Is needed sign the transaction ===
  int emv_is_need_signature(void)


'''Parameters'''
=== <big>Set the parameter for force online</big> ===
  <syntaxhighlight lang="java">int emv_set_force_online(int flag)</syntaxhighlight >


'''Returns'''
{|class="wizarpostable"
The result , = 1, need sign; =0 not need sign.
|-
! scope="row" colspan="2" | Parameters
|-
| flag || '''int:''' 1:Yes;0:No.
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , = 1, force online; =0 not force online.
|}


=== Set the parameter for force online ===
  int emv_set_force_online(int flag)


'''Parameters'''
=== <big>Read transaction record from the card</big> ===
  <syntaxhighlight lang="java">int emv_get_card_record(uint8_t *data, int dataLength)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| data || '''uint8_t *:''' transaction record.
|-
| dataLength || '''int:''' accepted max length for the transaction record.
|}
{|
{|
|-
|-
| ''flag'' || int || 1:Yes;0:No.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , >= 0, record count; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , = 1, need sign; =0 not need sign.


=== Read transaction record from the card ===
  int emv_get_card_record(uint8_t *data, int dataLength)


'''Parameters'''
=== <big>Get application list</big> ===
  <syntaxhighlight lang="java">int emv_get_candidate_list(uint8_t *data, int dataLength)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| data || '''uint8_t *:''' application list as "LV" format.
|-
| dataLength || '''int:''' accepted max length for application list.
|}
{|
{|
|-
|-
| ''data'' || uint8_t * || transaction record.
|  
|}
{|class="wizarpostable"
|-
|-
| ''dataLength'' || int|| accepted max length for the transaction record.
!  scope="row" colspan="2" | Returns
|-
| int || The result , >= 0, application count; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0, record count; <0 [[Error_code|error code]].


=== Get application list ===
  int emv_get_candidate_list(uint8_t *data, int dataLength)


'''Parameters'''
===  <big>Set the selected index for application selection</big>===
{|
  <syntaxhighlight lang="java">int emv_set_candidate_list_result(int index)</syntaxhighlight >
 
{|class="wizarpostable"
|-
|-
| ''data'' || uint8_t * || application list as "LV" format.
! scope="row" colspan="2" | Parameters
|-
|-
| ''dataLength'' || int|| accepted max length for application list.
| index || '''int:''' the selected index (started by 0).
|}
|}
'''Returns'''
The result , >= 0, application count; <0 [[Error_code|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).
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0,success; <0 [[Error_code|error code]].


===  Set the result for cardholder ID check===
  int emv_set_id_check_result(int result)


'''Parameters'''
===  <big>Set the result for cardholder ID check</big>===
  <syntaxhighlight lang="java">int emv_set_id_check_result(int result)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| result || '''int:''' ID Type（9F62）、 ID Number(9F61) 0: check Fail， 1:check success.
|}
{|
{|
|-
|-
| ''result'' || int|| ID Type（9F62）、 ID Number(9F61) 0: check Fail， 1:check success.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
| int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0,success; <0 [[Error_code|error code]].




=== Set the result for Online PIN ===
=== <big>Set the result for Online PIN</big> ===
   int emv_set_online_pin_entered(int result)
   <syntaxhighlight lang="java">int emv_set_online_pin_entered(int result)</syntaxhighlight >
 
{|class="wizarpostable"
'''Parameters'''
|-
! scope="row" colspan="2" | Parameters
|-
| result || '''int:''' 0: Online PIN not input， 1:Online PIN inputted.
|}
{|
{|
|-
|-
| ''result'' || int|| 0: Online PIN not input， 1:Online PIN inputted.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
| int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0,success; <0 [[Error_code|error code]].


=== Set acceptance for Bypass PIN ===
  int emv_set_pin_bypass_confirmed(int result)


'''Parameters'''
=== <big>Set acceptance for Bypass PIN</big> ===
  <syntaxhighlight lang="java">int emv_set_pin_bypass_confirmed(int result)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| result || '''int:''' 0: refused bypass pin， 1: accepted bypass pin.
|}
{|
{|
|-
|-
| ''result'' || int|| 0: refused bypass pin， 1: accepted bypass pin.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
| int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0,success; <0 [[Error_code|error code]].


=== Set the result for online certification ===
  int emv_set_online_result(int result,unsigned char *respCode,unsigned char *issuerRespData,int issuerRespDataLength)


=== <big>Set the result for online certification</big> ===
  <syntaxhighlight lang="java">int emv_set_online_result(int result,unsigned char *respCode,unsigned char *issuerRespData,int issuerRespDataLength)</syntaxhighlight >


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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.
|}
{|
{|
|-
|-
| ''result'' || int|| -1:communication failed； 0: host refused； 1: host accepted.
|  
|-
|}
| ''respCode'' || unsigned char *|| 2 bytes response code from the host.
{|class="wizarpostable"
|-
|-
| ''issuerRespData'' || unsigned char *|| the emv data from the host.
!  scope="row" colspan="2" | Returns
|-
|-
| ''issuerRespDataLength'' || int||  the length of the emv data from the host.
| int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result , >= 0,success; <0 [[Error_code|error code]].
== Setup EMVparameters ==
=== Clear AID info ===
  int emv_aidparam_clear(void)


'''Parameters'''
=== <big>Get Kernel checksum</big> ===
  <syntaxhighlight lang="java">int emv_get_kernel_checksum(unsigned char *buffer, int bufferLength)</syntaxhighlight >


'''Returns'''
{|class="wizarpostable"
The result , >= 0,success; <0 [[Error_code|error code]].
|-
! scope="row" colspan="2" | Parameters
|-
| buffer || '''unsigned char *:''' the value of emv kernel checksum.
|-
| bufferLength || '''int:''' accepted max length.
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , >= 0,the length of kernel checksum; <0 [[Error_code|error code]].
|}


=== Add AID info ===
=== <big>Get Configuration checksum</big> ===
   int emv_aidparam_add( uint8_t *data, int dataLength)
   <syntaxhighlight lang="java">int emv_get_config_checksum(unsigned char *buffer, int bufferLength)</syntaxhighlight >


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| buffer || '''unsigned char *:''' the value of configuration checksum.
|-
| bufferLength || '''int:''' accepted max length.
|}
{|
{|
|-
|-
| ''data'' || uint8_t * || see form below， format is TLV.
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result , >= 0,the length of configuration checksum; <0 [[Error_code|error code]].
|}
 
== <big>Setup EMVparameters</big> ==
=== <big>Clear AID info</big> ===
  <syntaxhighlight lang="java">int emv_aidparam_clear(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|-
| ''dataLength'' || int || the length of the data.
| int || The result , >= 0,success; <0 [[Error_code|error code]].
|}
|}


=== <big>Add AID info</big> ===
  <syntaxhighlight lang="java">int emv_aidparam_add( uint8_t *data, int dataLength)</syntaxhighlight >
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| data || '''uint8_t *:''' see form below， format is TLV.
|-
| dataLength || '''int:''' the length of the data.
|}
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 469: Line 705:
| Default TDOL || b || Var. || DF22
| Default TDOL || b || Var. || DF22
|}
|}
'''Returns'''
{|
The result , >= 0,success; <0 [[Error_code|error code]].
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Clear CAPK info</big> ===
  <syntaxhighlight lang="java">int emv_capkparam_clear(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Add CAPK info</big> ===
  <syntaxhighlight lang="java">int emv_capkparam_add( uint8_t *data, int dataLength)</syntaxhighlight >
 
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| data || '''uint8_t *:''' see form below， format is TLV.
|-
| dataLength || '''int:''' the length of the data.
|}
{| class="wikitable"
|-
! 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
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Set EMV terminal parameters</big> ===
  <syntaxhighlight lang="java">int emv_terminal_param_set( uint8_t *TerminalParam)</syntaxhighlight>
 
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| TerminalParam || '''uint8_t *:''' see form below.
|}
<syntaxhighlight lang="c">
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;
</syntaxhighlight >
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Clear Exception File</big> ===
  <syntaxhighlight lang="java">int emv_exception_file_clear(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Add Exception File</big> ===
  <syntaxhighlight lang="java">int emv_exception_file_add( unsigned char *exceptFile)</syntaxhighlight >
 
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| exceptFile || '''unsigned char *:''' see form below.
|}
<syntaxhighlight lang="c">
Typedef struct{
unsigned char cardNo[19]; // PAN
unsigned char panSequence; // PAN Sequence Number
}ExceptionFile
</syntaxhighlight >
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Clear Revoked Certicates</big> ===
  <syntaxhighlight lang="java">int emv_revoked_cert_clear(void)</syntaxhighlight >
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
 
 
=== <big>Add revoked Certificate</big> ===
  <syntaxhighlight lang="java">int emv_revoked_cert_add( uint8_t *revokedCert)</syntaxhighlight >
 
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| revokedCert || '''uint8_t *:''' see form below.
|}
<syntaxhighlight lang="c">
Typedef struct{
unsigned char rid[5];
unsigned char capki;
}RevokedCert
</syntaxhighlight >
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}

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.
Retrieved from "http://sdkwiki.wizarpos.com/index.php?title=EMV_API&oldid=675"