PINPAD API
Functions
The calling sequence is open>kick_out>close
open
int pinpad_open()
Open the PINPad device. This operation should be used before other operations.
Parameters
Returns
The result code, >= 0, success; <0 error code.
close
int pinpad_close()
Close the PINPad device. The open and close apis are pair operations. If you don’t want to use this device, you should call the close api to release this device.
Parameters
Returns
The result code, >= 0, success; <0 error code.
show_text
int pinpad_show_text(int nLineIndex, char* strText, int nLength, int nFlagSound)
Show text in the specified line.
Parameters
| nLineIndex | int | Line number to display, 0 or 1 |
| strText | char* | Text to show, String.getBytes() |
| nLength | int | Text length, the length maxsize is 14 |
| nFlagSound | int | Not used |
Returns
The result code, >= 0, success; <0 error code.
update_user_key
int pinpad_update_user_key(int nMasterKeyID, int nUserKeyID, unsigned char* pCipherNewUserKey, int nCipherNewUserKeyLength)
Update the user key. You should check the cipher user key by yourself through the specified master key and check value obtained from the server or other. The algorithm which using to encrypt user key is from select_key, but if not calling select key before update, the default algorithm is 3DES.
Parameters
| nMasterKeyID | int | Master key id |
| nUserKeyID | int | User key id |
| pCipherNewUserKey | unsigned char* | New user key in cipher text |
| nCipherNewUserKeyLength | int | Length of new user key |
Returns
The result code, >= 0, success; <0 error code.
update_user_key_with_check
int pinpad_update_user_key_with_check(int nMasterKeyID, int nUserKeyID, unsigned char *pCipherNewUserKey, int nCipherNewUserKeyLength, int nKeyUsge, unsigned char *pCheckValue, int nCheckValueLen)
Update the user key with check value. You don’t need to check the cipher user key by yourself. The algorithm which using to encrypt user key is from select_key, but if not calling select key before update, the default algorithm is 3DES.
Parameters
| nMasterKeyID | int | Master key id |
| nUserKeyID | int | User key id |
| pCipherNewUserKey | unsigned char* | New user key in cipher text |
| nCipherNewUserKeyLength | int | Length of new user key |
| nKeyUsge | int | Key type. 0--PIN key;1--MAC key;2—Data key |
| pCheckValue | unsigned char* | Check value of user key |
| nCheckValueLen | int | Length of new user keyLength of check value, 4 bytes in general |
Returns
The result code, >= 0, success; <0 error code.
set_pin_length
int pinpad_set_pin_length(int nLength, int nFlag)
Set the max or min length of PIN. When you call the calculate_pin_block api, the number you can input is no more than the max length.
Parameters
| nLength | int | PIN length |
| nFlag | int | Flag, 0--min length;1--max length |
Returns
The result code, >= 0, success; <0 error code.
get_serial_number
int pinpad_get_serial_number(unsigned char* pData,unsigned int nBufferLength)
Get serial number from the PINPad.
Parameters
| pData | unsigned char* | Serial number buffer |
| nBufferLength | unsigned int | Length of buffer |
Returns
The result code, >= 0, success; <0 error code.
select_key
int pinpad_select_key(int nKeyType, int nMasterKeyID, int nUserKeyID, int nAlgorith)
Select master key and user key before encryption operations. If the device is external PINPad, the user key id is 0-1 when nKeyType is master-session pair. If called before update user key, the user key is encrypted using the algorithm which defined by nAlgorith parameter.If the terminal device is a WIZARHAND_Q1 or Q2, the user key id is 0-2 when nKeyType is master-session pair.
Parameters
| nKeyType | int | 1 : TDUKPT, 2 : MASTER-SESSION PAIR |
| nMasterKeyID | int | Master key id, 0-9 when nKeyType is master-session; Master key id, 0,1,2 when nKeyType is TDUKPT |
| nUserKeyID | int | User key id, used when nKeyType is master-session. |
| nAlgorith | int | 1:3DES;2:SM4;3:AES |
Returns
The result code, >= 0, success; <0 error code.
calculate_pin_block
int pinpad_calculate_pin_block(unsigned char* pASCIICardNumber, int nCardNumberLength, unsigned char* pPinBlockBuffer, int nPinBlockBufferLength, int nTimeout_MS, int nFlagSound)
Calculate the PIN block of the inputted PIN. You should call select_key at first. The user key should be a PIN key whose id is 0 in general. The length of card number is normally 13-19. The max waiting time for PIN input is 60s, and the two PIN input time span is 10s, otherwise this API will return error code.
Parameters
| pASCIICardNumber | unsigned char* | Card number in ASCII format |
| nCardNumberLength | int | Length of card number |
| pPinBlockBuffer | unsigned char* | buffer for saving PIN block |
| nPinBlockBufferLength | int | Length of buffer |
| nTimeout_MS | int | Timeout waiting for user input in milliseconds. If it is less than 0, then wait forever. |
| nFlagSound | int | Not used |
Returns
The result code, >= 0, success; <0 error code.