com.cloudpos.pinpad

Interface PINPadDevice

All Superinterfaces:

Device

public interface PINPadDevice
extends Device

The PINPadDevice interface defines the API for interacting with PIN Pad devices. This interface allows applications to control the operations of a PIN Pad device for tasks like PIN entry, encryption, and key management.

An instance of PINPadDevice is obtained as follows:

 PINPadDevice pinPadDevice = (PINPadDevice) POSTerminal.getInstance().getDevice("com.cloudpos.device.pinpad");
 

"com.cloudpos.device.pinpad" is the identifier for the PINPad device, as defined by the specific implementation.

Different operations and permissions are associated with this device:

1. android.permission.CLOUDPOS_PIN_GET_PIN_BLOCK: Allows listenForPinBlock(com.cloudpos.pinpad.KeyInfo, java.lang.String, boolean, com.cloudpos.OperationListener, int) and waitForPinBlock(com.cloudpos.pinpad.KeyInfo, java.lang.String, boolean, int).
2. android.permission.CLOUDPOS_PIN_MAC: Allows calculateMac(com.cloudpos.pinpad.KeyInfo, int, byte[]).
3. android.permission.CLOUDPOS_PIN_ENCRYPT_DATA: Allows encryptData(com.cloudpos.pinpad.KeyInfo, byte[]).
4. android.permission.CLOUDPOS_PIN_UPDATE_USER_KEY: Allows updateUserKey(int, int, byte[], int, byte[]).

See Also:

Device

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALGO_CHECK_VALUE_DEFAULT
static int	ALGO_CHECK_VALUE_SE919
static int	CHECK_TYPE_CUP
static int	CHECK_TYPE_NONE
static int	KEY_TYPE_FIX
static int	KEY_TYPE_MK_SK
static int	KEY_TYPE_PUBLIC
static int	KEY_TYPE_TDUKPT
static int	KEY_TYPE_TDUKPT_2009
static int	KEY_TYPE_TDUKPT_2009_RESPONSE
static int	USER_KEY_ID_DATA
static int	USER_KEY_ID_MAC
static int	USER_KEY_ID_PIN

Method Summary

Modifier and Type	Method and Description
byte[]	calculateMac(KeyInfo keyInfo, int macFlag, byte[] plain) Calculates the MAC using the current user key as defined in KeyInfo.
byte[]	calculateResponseMac(KeyInfo keyInfo, byte[] plainData, int macFlag) Calculates the MAC (Message Authentication Code) using the TDUKPT method and a response MAC key.
int	changePin(KeyInfo keyInfo, byte[] cardNum, byte[] pinOld, byte[] pinNew, int[] lengthResult, int timeout) Changes the user's PIN.
void	clearText() Clears any displayed text from the PINPad's LCD screen.
int	createPin(KeyInfo keyInfo, byte[] cardNum, byte[] pinNew, int timeout, int nFlagSound) Creates a new PIN.
byte[]	encryptData(KeyInfo keyInfo, byte[] plain) Encrypts data using the specified key.
byte[]	encryptData(KeyInfo keyInfo, byte[] plain, int mode, byte[] IV, int IVLen) Encrypts data using the user-specified key with additional encryption options.
int	getDukptStatus(int dukptID, byte[] KSNBuf) Gets the status of a DUKPT Key.
int	getLastPINLength() Retrieves the length of the last input PIN.
int	getMkStatus(int mkId) Checks the status of a Master Key.
byte[]	getRandom(int length) Generates random data of a specified length.
byte[]	getSessionKeyCheckValue(int masterKeyID, int userKeyID, int algoCheckValue) Retrieves the check value for a session key.
int	getSkStatus(int mkId, int skID) Checks the status of a Session Key.
java.lang.String	getSN() Retrieves the serial number of the PINPad device.
void	listenForOfflinePin(boolean voicePrompt, OperationListener listener, int timeout) Waits for the user to enter their offline PIN.
void	listenForPinBlock(KeyInfo keyInfo, java.lang.String pan, boolean voicePrompt, OperationListener listener, int timeout) Listens for user PIN input and calculates the encrypted PIN block asynchronously.
void	listenForPinBlock(KeyInfo keyInfo, java.lang.String pan, boolean voicePrompt, OperationListener listener, int timeout, int mode, byte[] IV) Asynchronously listens for user PIN input and calculates an encrypted PIN block with a specific mode.
void	open(int logicalID) Opens the PINPad device for operation.
int	selectPinblockFormat(int nPinblockFormat) Selects the pinblock format to use.
boolean	setAllowByPass(boolean allow) Allows or disallows bypassing the PIN for online EMV transactions.
boolean	setGUIConfiguration(int flag, byte[] data) Configures the PINPAD GUI.
boolean	setGUIConfiguration(java.lang.String key, java.lang.String value) Configures the PINPAD GUI, including style, sound, and colors.
void	setPINLength(int minLen, int maxLen) Sets the minimum and maximum length of the PIN to be entered by the user.
boolean	setupCallbackHandler(com.cloudpos.jniinterface.PinPadCallbackHandler handler) Sets up a callback for customizing the PINPAD UI.
void	showText(int lineIndex, java.lang.String message) Displays a text message on the PINPad's LCD screen.
void	showText(int lineIndex, java.lang.String message, boolean voicePrompt) Displays a text message on the PINPad's LCD screen.
void	updateMasterKey(int masterKeyID, byte[] oldMasterKey, byte[] newMasterKey) Updates the master key used by the PINPad device.
void	updateMasterKeyWithCheck(int masterKeyID, byte[] cipherNewMasterKey, byte[] checkValue, int algoCheckValue) Updates the master key, which must be encrypted by a transport key.
void	updateMasterKeyWithCheckByMK(int masterKeyID, byte[] cipherNewMasterKey, byte[] checkValue, int algoCheckValue) Updates the master key, which must be encrypted by the old master key.
void	updateUserKey(int masterKeyID, int userKeyID, byte[] cipherNewUserKey) Updates the user key (session key) encrypted by the master key using 3DES algorithm.
void	updateUserKey(int masterKeyID, int userKeyID, byte[] cipherNewUserKey, int userKeyType) Updates the user key (session key) encrypted by the master key using 3DES algorithm.
void	updateUserKey(int masterKeyID, int userKeyID, byte[] cipherNewUserKey, int checkType, byte[] checkValue) Updates the user key (session key) encrypted by the master key using 3DES algorithm.
void	updateUserKey(int masterKeyID, int userKeyID, byte[] cipherNewUserKey, int checkType, byte[] checkValue, KeyInfo keyInfo) Updates the user key(session key) with additional check value options.
void	updateUserKeyWithCheck(int masterKeyID, int userKeyID, byte[] cipherNewUserKey, int userKeyType, byte[] checkValue, int algoCheckValue) Updates the user key(session key).
int	updateUserKeyWithTR31Format(int masterKeyID, int userKeyID, byte[] tr31Msg) Updates the user key with TR31 formatted message.
boolean	verifyResponseMac(KeyInfo keyInfo, byte[] plainData, int macFlag, byte[] macData, int nDirection) Verifies the response MAC.
PINPadOperationResult	waitForOfflinePin(boolean voicePrompt, int timeout) A synchronous version of 'listenForOfflinePin'.
PINPadOperationResult	waitForPinBlock(KeyInfo keyInfo, java.lang.String pan, boolean voicePrompt, int timeout) Synchronously waits for user PIN input and calculates the encrypted PIN block.
PINPadOperationResult	waitForPinBlock(KeyInfo keyInfo, java.lang.String pan, boolean voicePrompt, int timeout, int mode, byte[] IV) Synchronously calculates an encrypted PIN block with a specific mode.

Methods inherited from interface com.cloudpos.Device

cancelRequest, close, getFailCount, getUsageCount, open

Field Detail

KEY_TYPE_TDUKPT

static final int KEY_TYPE_TDUKPT

See Also:

Constant Field Values

KEY_TYPE_MK_SK

static final int KEY_TYPE_MK_SK

See Also:

Constant Field Values

KEY_TYPE_PUBLIC

static final int KEY_TYPE_PUBLIC

See Also:

Constant Field Values

KEY_TYPE_FIX

static final int KEY_TYPE_FIX

See Also:

Constant Field Values

KEY_TYPE_TDUKPT_2009

static final int KEY_TYPE_TDUKPT_2009

See Also:

Constant Field Values

KEY_TYPE_TDUKPT_2009_RESPONSE

static final int KEY_TYPE_TDUKPT_2009_RESPONSE

See Also:

Constant Field Values

USER_KEY_ID_PIN

static final int USER_KEY_ID_PIN

See Also:

Constant Field Values

USER_KEY_ID_MAC

static final int USER_KEY_ID_MAC

See Also:

Constant Field Values

USER_KEY_ID_DATA

static final int USER_KEY_ID_DATA

See Also:

Constant Field Values

CHECK_TYPE_NONE

static final int CHECK_TYPE_NONE

See Also:

Constant Field Values

CHECK_TYPE_CUP

static final int CHECK_TYPE_CUP

See Also:

Constant Field Values

ALGO_CHECK_VALUE_DEFAULT

static final int ALGO_CHECK_VALUE_DEFAULT

See Also:

Constant Field Values

ALGO_CHECK_VALUE_SE919

static final int ALGO_CHECK_VALUE_SE919

See Also:

Constant Field Values

Method Detail

open

void open(int logicalID)
   throws DeviceException

Opens the PINPad device for operation.

Parameters:

logicalID - The logical ID to identify the specific PINPad device to open.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

showText

void showText(int lineIndex,
              java.lang.String message)
       throws DeviceException

Displays a text message on the PINPad's LCD screen.

Parameters:

lineIndex - The line number (e.g., 0 or 1) where the message should be displayed.

message - The text message to be displayed.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

showText

void showText(int lineIndex,
              java.lang.String message,
              boolean voicePrompt)
       throws DeviceException

Displays a text message on the PINPad's LCD screen.

Parameters:

lineIndex - The line number (e.g., 0 or 1) where the message should be displayed.

message - The text message to be displayed.

voicePrompt - voicePrompt Indicates whether a voice prompt should be played (true/false). Currently not supported.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

clearText

void clearText()
        throws DeviceException

Clears any displayed text from the PINPad's LCD screen.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateMasterKey

void updateMasterKey(int masterKeyID,
                     byte[] oldMasterKey,
                     byte[] newMasterKey)
              throws DeviceException

Updates the master key used by the PINPad device.

Parameters:

masterKeyID - The index of the master key to be updated.

oldMasterKey - The current master key.

newMasterKey - The new master key to replace the old one.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKey

void updateUserKey(int masterKeyID,
                   int userKeyID,
                   byte[] cipherNewUserKey,
                   int checkType,
                   byte[] checkValue)
            throws DeviceException

Updates the user key (session key) encrypted by the master key using 3DES algorithm.

Parameters:

masterKeyID - Index of the master key.

userKeyID - Index of the user key.

cipherNewUserKey - New user key encrypted with the master key.

checkType - Type of check value used: CHECK_TYPE_NONE or CHECK_TYPE_CUP.

checkValue - Check value for the key.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKey

void updateUserKey(int masterKeyID,
                   int userKeyID,
                   byte[] cipherNewUserKey,
                   int userKeyType)
            throws DeviceException

Updates the user key (session key) encrypted by the master key using 3DES algorithm.

Parameters:

masterKeyID - Index of the master key.

userKeyID - Index of the user key.

cipherNewUserKey - New user key encrypted with the master key.

userKeyType - Type of user key used: USER_KEY_ID_PIN, USER_KEY_ID_MAC or USER_KEY_ID_DATA.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKey

void updateUserKey(int masterKeyID,
                   int userKeyID,
                   byte[] cipherNewUserKey)
            throws DeviceException

Updates the user key (session key) encrypted by the master key using 3DES algorithm.

Parameters:

masterKeyID - Index of the master key.

userKeyID - Index of the user key.

cipherNewUserKey - New user key encrypted with the master key.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

encryptData

byte[] encryptData(KeyInfo keyInfo,
                   byte[] plain)
            throws DeviceException

Encrypts data using the specified key.

Parameters:

keyInfo - Details of the key used for encryption.

plain - The plain data to be encrypted.

Returns:

The encrypted data buffer.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

listenForPinBlock

void listenForPinBlock(KeyInfo keyInfo,
                       java.lang.String pan,
                       boolean voicePrompt,
                       OperationListener listener,
                       int timeout)
                throws DeviceException

Listens for user PIN input and calculates the encrypted PIN block asynchronously. The result is sent to the 'handleResult' method of the provided 'OperationListener'. This method must be able to handle cancelRequest() in case of a timeout.

Parameters:

keyInfo - Key configuration for PIN calculation.

pan - ASCII string of the card number.

voicePrompt - If true, plays audio for user notification.

listener - Receives operation results.

timeout - Maximum time to wait for input in milliseconds. Note: * - If 'timeout' equals 'FOREVER', waits indefinitely for input. * - If 'timeout' equals 'IMMEDIATE', immediately processes the input.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

waitForPinBlock

PINPadOperationResult waitForPinBlock(KeyInfo keyInfo,
                                      java.lang.String pan,
                                      boolean voicePrompt,
                                      int timeout)
                               throws DeviceException

Synchronously waits for user PIN input and calculates the encrypted PIN block. Returns the operation result directly.

Parameters:

keyInfo - Key configuration for PIN calculation.

pan - ASCII string of the card number.

voicePrompt - If true, plays audio for user notification.

timeout - Maximum time to wait for input in milliseconds. Note: - If 'timeout' equals 'FOREVER', waits indefinitely for input. - If 'timeout' equals 'IMMEDIATE', immediately processes the input.

Returns:

Encrypted PIN block result.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

waitForPinBlock

PINPadOperationResult waitForPinBlock(KeyInfo keyInfo,
                                      java.lang.String pan,
                                      boolean voicePrompt,
                                      int timeout,
                                      int mode,
                                      byte[] IV)
                               throws DeviceException

Synchronously calculates an encrypted PIN block with a specific mode.

Parameters:

keyInfo - Key configuration for PIN calculation.

pan - ASCII string of the card number.

voicePrompt - If true, plays audio for user notification.

timeout - Maximum time to wait for input in milliseconds. Note: - If 'timeout' equals 'FOREVER', waits indefinitely for input. - If 'timeout' equals 'IMMEDIATE', immediately processes the input.

mode - Encryption mode (default 0(mode none), MODE_ESP: 10).

IV - Initialization Vector, required for MODE_ESP, 8 bytes.

Returns:

Encrypted PIN block result.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

listenForPinBlock

void listenForPinBlock(KeyInfo keyInfo,
                       java.lang.String pan,
                       boolean voicePrompt,
                       OperationListener listener,
                       int timeout,
                       int mode,
                       byte[] IV)
                throws DeviceException

Asynchronously listens for user PIN input and calculates an encrypted PIN block with a specific mode. Results are sent to the 'OperationListener'.

Parameters:

keyInfo - Key configuration for PIN calculation.

pan - ASCII string of the card number.

voicePrompt - If true, plays audio for user notification.

listener - Receives operation results.

timeout - Maximum time to wait for input in milliseconds.Note: - If 'timeout' equals 'FOREVER', waits indefinitely for input. - If 'timeout' equals 'IMMEDIATE', immediately processes the input.

mode - Encryption mode (default 0(mode none), MODE_ESP: 10).

IV - Initialization Vector, required for MODE_ESP, 8 bytes.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

listenForOfflinePin

void listenForOfflinePin(boolean voicePrompt,
                         OperationListener listener,
                         int timeout)
                  throws DeviceException

Waits for the user to enter their offline PIN. This method only notifies the result of the input, without returning the actual PIN to the app.

Parameters:

voicePrompt - If true, plays audio to notify the user.

listener - The operation listener that will receive the result.

timeout - Maximum time to wait for input, in milliseconds. Note: - If 'timeout' equals 'FOREVER', waits indefinitely for input. - If 'timeout' equals 'IMMEDIATE', immediately processes the input.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

waitForOfflinePin

PINPadOperationResult waitForOfflinePin(boolean voicePrompt,
                                        int timeout)
                                 throws DeviceException

A synchronous version of 'listenForOfflinePin'. Waits for and processes the offline PIN input within the specified timeout.

Parameters:

voicePrompt - If true, plays audio to notify the user.

timeout - Maximum time to wait for input, in milliseconds.

Returns:

The result of the PIN pad operation.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

calculateMac

byte[] calculateMac(KeyInfo keyInfo,
                    int macFlag,
                    byte[] plain)
             throws DeviceException

Calculates the MAC using the current user key as defined in KeyInfo.

Parameters:

keyInfo - Key configuration used for MAC calculation.

macFlag - Algorithm flag for MAC calculation：

1. AlgorithmConstants.ALG_MAC_METHOD_ECB.
2. AlgorithmConstants.ALG_MAC_METHOD_X99.
3. AlgorithmConstants.ALG_MAC_METHOD_ECB_FIRST.
4. AlgorithmConstants.ALG_MAC_METHOD_SE919.

plain - Data for which the MAC is to be calculated.

Returns:

The calculated MAC data buffer.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

setPINLength

void setPINLength(int minLen,
                  int maxLen)
           throws DeviceException

Sets the minimum and maximum length of the PIN to be entered by the user.

Parameters:

minLen - The minimum length of the PIN.

maxLen - The maximum length of the PIN.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getSN

java.lang.String getSN()
                throws DeviceException

Retrieves the serial number of the PINPad device.

Returns:

The serial number of the PINPad.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getRandom

byte[] getRandom(int length)
          throws DeviceException

Generates random data of a specified length.

Parameters:

length - The length of the random data to be generated.

Returns:

A buffer containing the generated random data.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKeyWithCheck

void updateUserKeyWithCheck(int masterKeyID,
                            int userKeyID,
                            byte[] cipherNewUserKey,
                            int userKeyType,
                            byte[] checkValue,
                            int algoCheckValue)
                     throws DeviceException

Updates the user key(session key). The buffer is the cipher user key which encrypted by master key. Assign the check value and the algorithm of the check value.

Parameters:

masterKeyID - Master key index

userKeyID - User key index

cipherNewUserKey - ciphered user key

userKeyType - user key type. 0--PIN key;1--MAC key;2--Data key

checkValue - check value of user key

algoCheckValue - algorithm of calculate the checkvalue used: ALGO_CHECK_VALUE_DEFAULT or ALGO_CHECK_VALUE_SE919.

Throws:

DeviceException - for the standard reasons that are documented in DeviceException.

updateMasterKeyWithCheck

void updateMasterKeyWithCheck(int masterKeyID,
                              byte[] cipherNewMasterKey,
                              byte[] checkValue,
                              int algoCheckValue)
                       throws DeviceException

Updates the master key, which must be encrypted by a transport key.

Parameters:

masterKeyID - Master key index.

cipherNewMasterKey - Ciphered new master key.

checkValue - Check value for the key.

algoCheckValue - Algorithm used for check value calculation: ALGO_CHECK_VALUE_DEFAULT or ALGO_CHECK_VALUE_SE919.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateMasterKeyWithCheckByMK

void updateMasterKeyWithCheckByMK(int masterKeyID,
                                  byte[] cipherNewMasterKey,
                                  byte[] checkValue,
                                  int algoCheckValue)
                           throws DeviceException

Updates the master key, which must be encrypted by the old master key.

Parameters:

masterKeyID - Master key index.

cipherNewMasterKey - Ciphered new master key, encrypted by the old master key.

checkValue - Check value for the key.

algoCheckValue - Algorithm used for check value calculation: ALGO_CHECK_VALUE_DEFAULT or ALGO_CHECK_VALUE_SE919.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

encryptData

byte[] encryptData(KeyInfo keyInfo,
                   byte[] plain,
                   int mode,
                   byte[] IV,
                   int IVLen)
            throws DeviceException

Encrypts data using the user-specified key with additional encryption options.

Parameters:

keyInfo - Information about the key used for encryption.

plain - The plain data to be encrypted.

mode - Encryption mode: MODE_EBC(0), MODE_CBC(1), MODE_CFB(2) or MODE_OFB.NoPadding(3).

IV - Initial vector for the encryption (used in certain modes: CBC, CFB, OFB mode).

IVLen - Length of the initial vector, must be equal to block length according to the algorithm.

Returns:

Encrypted data buffer.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKey

void updateUserKey(int masterKeyID,
                   int userKeyID,
                   byte[] cipherNewUserKey,
                   int checkType,
                   byte[] checkValue,
                   KeyInfo keyInfo)
            throws DeviceException

Updates the user key(session key) with additional check value options.

Parameters:

masterKeyID - Master key index.

userKeyID - User key index.

cipherNewUserKey - Ciphered new user key.

checkType - Type of check value used: CHECK_TYPE_NONE or CHECK_TYPE_CUP.

checkValue - Check value for the key.

keyInfo - Key configuration used for PIN calculation(used in JNI:selectKey).

Throws:

DeviceException - for standard reasons as documented in DeviceException.

updateUserKeyWithTR31Format

int updateUserKeyWithTR31Format(int masterKeyID,
                                int userKeyID,
                                byte[] tr31Msg)
                         throws DeviceException

Updates the user key with TR31 formatted message.

Parameters:

masterKeyID - Index of the master key.

userKeyID - Index of the user key to be updated.

tr31Msg - TR31 formatted key update message.

Returns:

An integer indicating the status of the operation: A non-negative number for success, a negative number for an error.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getSessionKeyCheckValue

byte[] getSessionKeyCheckValue(int masterKeyID,
                               int userKeyID,
                               int algoCheckValue)
                        throws DeviceException

Retrieves the check value for a session key.

Parameters:

masterKeyID - Index of the master key.

userKeyID - Index of the user key.

algoCheckValue - Algorithm used for the check value calculation: ALGO_CHECK_VALUE_DEFAULT or ALGO_CHECK_VALUE_SE919.

Returns:

The check value of the session key.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

verifyResponseMac

boolean verifyResponseMac(KeyInfo keyInfo,
                          byte[] plainData,
                          int macFlag,
                          byte[] macData,
                          int nDirection)
                   throws DeviceException

Verifies the response MAC.

Parameters:

keyInfo - Key configuration used for MAC verification.

plainData - Data used for MAC calculation.

macFlag - MAC calculation algorithm flag:

1. AlgorithmConstants.ALG_MAC_METHOD_ECB.
2. AlgorithmConstants.ALG_MAC_METHOD_X99.
3. AlgorithmConstants.ALG_MAC_METHOD_ECB_FIRST.
4. AlgorithmConstants.ALG_MAC_METHOD_SE919.

macData - MAC data to verify.

nDirection - Reserved for future use, currently should be set to 0.

Returns:

True if MAC verification is successful, false otherwise.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

calculateResponseMac

byte[] calculateResponseMac(KeyInfo keyInfo,
                            byte[] plainData,
                            int macFlag)
                     throws DeviceException

Calculates the MAC (Message Authentication Code) using the TDUKPT method and a response MAC key. Within a single open-close session, this method uses the same Key Serial Number (KSN) as the previous calculateMAC method call.

Parameters:

keyInfo - Configuration settings for the PINPad to calculate the MAC.

plainData - The data for which the MAC is to be calculated.

macFlag - Specifies the algorithm to be used for MAC calculation, with the following options:

1. AlgorithmConstants.ALG_MAC_METHOD_ECB.
2. AlgorithmConstants.ALG_MAC_METHOD_X99.
3. AlgorithmConstants.ALG_MAC_METHOD_ECB_FIRST.
4. AlgorithmConstants.ALG_MAC_METHOD_SE919.

Returns:

The calculated MAC as a data buffer.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

setGUIConfiguration

boolean setGUIConfiguration(int flag,
                            byte[] data)
                     throws DeviceException

Configures the PINPAD GUI. - For flag 1: Set alignment of the displayed asterisk (Left, Center, Right). - For flag 2: Set the title bar content. - For flag 3: Choose PINPAD UI style. Call this method each time the PINPAD device is opened.

Parameters:

flag - Determines the setting to be adjusted (1, 2, or 3).

data - Specifies the configuration based on the flag.

flag	data
1	0x00(Left)/0x01(Center)/0x02(Right)
2	content of title
3	data[0] = 0 default normal virtual data[0] = 1 big virtual data[0] = 2 Q3K data[0] = 3 horizontal virtual, landscape orientation data[0] = 4 Function button in bottom

Returns:

true if successful, false otherwise.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

setGUIConfiguration

boolean setGUIConfiguration(java.lang.String key,
                            java.lang.String value)
                     throws DeviceException

Configures the PINPAD GUI, including style, sound, and colors. Call this method each time the PINPAD device is opened.

Parameters:

key - The setting to configure (e.g., style, sound).

value - The desired value for the setting.

key	value	default
style	system	system
sound	true/false	false
displaybackcolor	RGB color	#6C8C4F
inputtextcolor	RGB color	#FFFFFF
disablebackgrounddarkening	true/false	false

Returns:

true if successful, false otherwise.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getMkStatus

int getMkStatus(int mkId)
         throws DeviceException

Checks the status of a Master Key.

Parameters:

mkId - The index of the master key.

Returns:

Negative for error, 0 if it doesn't exist, 1 if it exists.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getSkStatus

int getSkStatus(int mkId,
                int skID)
         throws DeviceException

Checks the status of a Session Key.

Parameters:

mkId - The master key index.

skID - The session key index.

Returns:

Negative for error, 0 if it doesn't exist, 1 if it exists.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getDukptStatus

int getDukptStatus(int dukptID,
                   byte[] KSNBuf)
            throws DeviceException

Gets the status of a DUKPT Key.

Parameters:

dukptID - The DUKPT key index.

KSNBuf - Buffer to store the Key Serial Number.

Returns:

Negative for error, 0 if it doesn't exist, positive for KSN data length.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

setAllowByPass

boolean setAllowByPass(boolean allow)
                throws DeviceException

Allows or disallows bypassing the PIN for online EMV transactions.

Parameters:

allow - Set to true to allow bypassing, false to disallow.

Returns:

true if successful.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

setupCallbackHandler

boolean setupCallbackHandler(com.cloudpos.jniinterface.PinPadCallbackHandler handler)
                      throws DeviceException

Sets up a callback for customizing the PINPAD UI.

Parameters:

handler - The callback handler for UI customization.

Returns:

true if successful, false if it fails.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

changePin

int changePin(KeyInfo keyInfo,
              byte[] cardNum,
              byte[] pinOld,
              byte[] pinNew,
              int[] lengthResult,
              int timeout)
       throws DeviceException

Changes the user's PIN.

Parameters:

keyInfo - Key configuration for calculation.

cardNum - Card number.

pinOld - Old PIN.

pinNew - New PIN.

lengthResult - Result of the length.

timeout - Time to wait for input in milliseconds.

Returns:

Non-negative for success, otherwise an error code.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

createPin

int createPin(KeyInfo keyInfo,
              byte[] cardNum,
              byte[] pinNew,
              int timeout,
              int nFlagSound)
       throws DeviceException

Creates a new PIN.

Parameters:

keyInfo - Key configuration for calculation.

cardNum - Card number in ASCII.

pinNew - Buffer to store the new PIN block.

timeout - Timeout for user input in milliseconds, negative for indefinite wait.

nFlagSound - Flag for voice prompt (0 for none, 1 for prompt).

Returns:

Negative for error, non-negative for success and length of the PIN block.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

selectPinblockFormat

int selectPinblockFormat(int nPinblockFormat)
                  throws DeviceException

Selects the pinblock format to use. Default format is ISO0. Notes on Pinblock Format Support and Handling: - Supported Formats: The HAL layer supports ISO0, ISO2, ISO4, and SM4 formats. - Case 0: ISO2 is exclusively for IC card offline PIN functions. The pinblock is stored in the hardware security module (HSM) and is inaccessible to the HAL layer, as it is not encrypted. - Case 1: When a key with a specific algorithm is injected, if the algorithm doesn't match the pinblock format, the HSM returns an error. A match leads to successful processing. - Case 2: Injecting a key without specifying an algorithm allows the HSM to choose the pinblock format based on your selection. - Case 3: If no pinblock format is selected, the HSM chooses one based on the algorithm of the injected key.

Parameters:

nPinblockFormat - Format index (0~5, ISO0/ISO1/ISO2/ISO3/ISO4/SM4).

Returns:

Negative for error, non-negative for success.

Throws:

DeviceException - for standard reasons as documented in DeviceException.

getLastPINLength

int getLastPINLength()
              throws DeviceException

Retrieves the length of the last input PIN.

Returns:

Length of the last input PIN.

Throws:

DeviceException - for standard reasons as documented in DeviceException.