> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/android/idevice.md). # IDevice ## cancelTransaction This function cancels a transaction. A transaction can only be cancelled before a card is presented. ```java boolean IDevice.cancelTransaction(); ``` **Return Value:** Returns true if cancelled. Otherwise, returns false. ## getCapabilities This function retrieves the capabilities of the device. ```java IDeviceCapabilities IDevice.getCapabilities(); ``` **Return Value:** Returns `IDeviceCapabilities` ## getConnectionInfo This function retrieves the connection information of the device. ```java ConnectionInfo IDevice.getConnectionInfo(); ``` **Return Value:** Returns `ConnectionInfo` ## getConnectionState This function retrieves the connection state of the device. ```java ConnectionState IDevice.getConnectionState(); ``` **Return Value:** Returns `CaptureType` This enum refers to the type of customer information to capture. | Enum | Description | | -------------------- | ---------------------------------- | | Unavailable | Capture unavailable | | PhoneNumber | Capture the phone number | | SocialSecurityNumber | Capture the social security number | | ZipCode | Capture the zip code | | EmployeeID | Capture Employee ID number | | BirthDate | Capture birth date in USA format | ### ConnectionState ## getDeviceConfiguration This function allows the host to get an `IDeviceConfiguration` to configure the device. ```java IDeviceConfiguration IDevice.getDeviceConfiguration(); ``` **Return Value:** Returns `IDeviceConfiguration`. ## getDeviceControl This function retrieves the device control interface to the device. ```java IDeviceControl IDevice.getDeviceControl(); ``` **Return Value:** Returns `IDeviceControl` ## getDeviceInfo This function returns an information class of the device. ```java DeviceInfo IDevice.getDeviceInfo(); ``` **Return Value:** Returns `DeviceInfo`. ### Name This function returns the name of the device assigned from `createDevice()`. > `String IDevice.Name();` **Return Value:** Returns the name of the device. ## requestPAN This function prompts the user to present their card and enter a PIN. A card is presented so that the device can retrieve the PAN, which is used for Format blocks requiring a PAN. The encrypted PIN block (EPB) will be returned in the event `OnEvent`. The data byte array may be passed to builder function `PANDataBuilder.GetPANData();` For DynaFlex devices, this function starts a PIN session on the first call and shall be called again to send the PIN status to the device for completing the PIN session. ```java boolean IDevice.requestPAN(PANRequest panRequest, PINRequest pinRequest); ``` ### PANRequest | Parameter | Type | Description | | -------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Timeout | byte | Wait time in seconds. | | PaymentMethods | List of PaymentMethod | List of the PaymentMethod enumeration. MSR = For magnetic stripe cards. Contact = For EMV chip cards. Contactless = For NFC contactless cards. ManualEntry = Manually entry, no card. When set, other payment methods must not be included. Barcode = For barcode. BarcodeEncrypted = For barcode with encrypted response. AppleVAS = For Apple VAS. GoogleVAS = For Google Wallet VAS. NFC = For NFC tag. | ### PINRequest | Parameter | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Timeout | byte | Wait time in seconds. | | PINMode | byte | PIN mode. Usage: `0x00` - Enter PIN `0x01` - Enter PIN Amount `0x02` - Reenter PIN Amount `0x03` - Reenter PIN `0x04` - Verify PIN For DynaFlex devices this is the User Interface Sequence: `0x01` - Present Card / Enter PIN (start session) `0x04` - Present Card / Enter PIN / Enter PIN Again (start session) On the second call to `requestPAN()`, send the PIN status: `0xFD` - Cancel PIN Session (end session) `0xFE` - PIN Entry Failed (end session) `0xFF` - PIN Entry Successful (end session) | | MinLength | byte | Minimum length of accepted PIN (>= 4). | | MaxLength | byte | Maximum length of accepted PIN (=< 12). | | Tone | byte | Tone to play when prompting for the PIN. Usage: `0x00` - No sound `0x01` - One beep `0x02` - Two beeps | | Format | byte | ISO format for the PIN block. | | PAN | String | First 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block. | **Return Value:** Returns true if successful. Otherwise, returns false. ## requestPIN This function prompts the user to enter a PIN. The host must supply the PAN if the Format block selected requires a PAN. The encrypted PIN block (EPB) will be returned in the event `OnEvent`. The data byte array may be passed to builder function `PINDataBuilder.GetPINData();` For DynaFlex devices, this function starts a PIN session on the first call and shall be called again to send the PIN status to the device for completing the PIN session. ```java boolean IDevice.requestPIN(PINRequest pinRequest); ``` ### PINRequest | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Timeout | byte | Wait time in seconds. | | PINMode | byte | PIN mode. Usage: `0x00` - Enter PIN `0x01` - Enter PIN Amount `0x02` - Reenter PIN Amount `0x03` - Reenter PIN `0x04` - Verify PIN For DynaFlex devices this is the User Interface Sequence: `0x00` - Enter PIN (start session) `0x02` - PIN Incorrect, Try Again (continue session) `0x03` - Enter PIN / Enter PIN Again (start session) `0x05` - Enter PIN Again (continue session) On the second call to `requestPIN()`, send the PIN status: `0xFD` - Cancel PIN Session (end session) `0xFE` - PIN Entry Failed (end session) `0xFF` - PIN Entry Successful (end session) | | MinLength | byte | Minimum length of accepted PIN (> 4). | | MaxLength | byte | Maximum length of accepted PIN (< 12). | | Tone | byte | Tone to play when prompting for the PIN. Usage: `0x00` - No sound `0x01` - One beep `0x02` - Two beeps | | Format | byte | ISO format for the PIN block. | | PAN | String | First 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block. | **Return Value:** Returns true if successful. Otherwise, returns false. ## requestSignature This function prompts the user to enter a signature. The response data will be returned in the event **OnEvent.** ```java boolean IDevice.requestSignature(); ``` **Return Value:** Returns true of successful. Otherwise, returns false. ## sendAuthorization This function sends the Authorization Response Code (ARPC) blob to the device. The response data will be returned in the event `OnEvent`. See EMV Transaction Flow for how to process an EMV transaction. ```java boolean IDevice.sendAuthorization(IData data); ``` ### Parameter | Parameter | Description | | --------- | ------------------- | | data | Contains ARPC blob. | **Return Value:** Returns true if successful. Otherwise, returns false. ## sendClassicNFCCommand This function sends a command to a NFC Mifare Classic Tag type 2. The NFC tag must first be activated by calling `startTransaction()` with NFC enabled. ```java boolean IDevice.sendClasicNFCCommand( IData data, boolean lastCommand, boolean encrypt); ``` ### Parameter | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data | Command to send to the NFC tag. For details of the command see NFC Classic commands table below or *D998200383 DynaFlex Family Programmer’s Manual (COMMANDS) section NFC/Mifare Pass Through Commands* | | lastCommand | Determines if this is the last NFC command to complete the operation. `true` = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling `startTransaction()` with NFC enabled. `false` = Expect more commands (Default). Either set to true or false, if the NFC tag command fails, device will provide a double beep. | | encrypt | Determines if data returned is to be encrypted. `true` = Encrypt data `false` = Do not encrypt data (Default) | **Return Value:** Returns true if successful. Otherwise, returns false. ## NFC Classic Commands | Command | Length | Field Value | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Mifare Read | 11 | Byte 0 – 0x30 – Read Command Byte 1 – Sector Number to Read Byte 2 – Start Block Number Byte 3 – End Block Number Byte 4 – Key Type, 0 = A, 1 = B Byte 5 to 10 = 6 Byte Key | | Mifare Write | var | Byte 0 – 0xA0 – Write Command Byte 1 – Sector Number to Write Byte 2 – Start Block Number Byte 3 – End Block Number Byte 4 – Key Type 0 = A, 1 = B Byte 5 to 10 = 6 Byte Key Byte 11 to x = Variable length Byte Data (16 bytes per block) | | Mifare Increment | 14 | Byte 0 – 0xC1 – Increment Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key Byte 10 to 13 = 4 Byte Operand | | Mifare Decrement | 14 | Byte 0 – 0xC0 – Decrement Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key Byte 10 to 13 = 4 Byte Operand | | Mifare Restore | 10 | Byte 0 – 0xC2 – Restore Command Byte 1 – Source Sector Number Byte 2 – Source Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key | | Mifare Transfer | 10 | Byte 0 – 0xB0 – Write the value from the Transfer Buffer into destination block number Byte 1 – Destination Sector Number Byte 2 – Destination Block number Byte 3 – Key Type 0 = A, 1 = B Byte 4 to 9 = 6 Byte Key | ## Response Data For NFC Classic Tag | Tag | Len | Value / Description | | --- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | 81 | var | Tag Response Code Byte 0 = 0x00 = Success Byte 0 = 0x01 = I/O Failed Byte 0 = 0x02 Authentication Failed Byte 1 = 0x01 = Block that Failed (optional) | | 82 | var | Encryption Control Payload | If unencrypted: | Tag | Len | Value / Description | | ----- | --- | ------------------- | | FC | var | NFC Data Container | | /DF7A | var | NFC Data | If encrypted: | Tag | Len | Value / Description | | ------- | --- | ----------------------------------------- | | /DFDF59 | var | Encrypted Data Primitive to be decrypted. | | /DFDF50 | var | Encrypted Data KSN | | /DFDF51 | 01 | Encrypted Data Encryption Type | **Example Unencrypted Payload** ``` 81 0100 (Tag Respons Code) 82 82036D (Encryption Control) FC 820369 (NFC Data Container) DF7A 820364 (NFC Data) 031391010F55047777772E6D616774656B2E636F6DFE00. . . www.magtek.com ``` **Example Encrypted Payload for Fast Read** ``` 81 0100 (Tag Response code) 82 820389 (Encryption Control) DFDF59 820370 (Encrypted Data Primitive) 03679DC03B4CA607E3A7D2B52C8E9F1B5CD3D85E7368425. . . DFDF50 0A (Encrypted Data KSN) FFFF9876543210200047 DFDF51 01 (Encrypted Data Type) 80 ``` ## sendDESFireNFCCommand This function sends a command to an NFC Mifare DESFire Tag Type 4. The NFC tag must first be activated by calling `startTransaction()` with NFC enabled. ```java boolean IDevice.sendDESFireNFCCommand( IData data, boolean lastCommand, boolean encrypt); ``` ### Parameter | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data | Command to send to the NFC tag. See DESFire Data Sheet (MF2DLHX0). Should follow ISO 7816-4 APDU format. For details of the command see *D998200383 DynaFlex Family Programmer’s Manual (COMMANDS)* section NFC/Mifare Pass Through Commands\_ | | lastCommand | Determines if this is the last NFC command to complete the operation. `true` = This is the last command. Device will provide a single beep after receiving a successful response from the NFC tag. To send subsequent commands, the NFC tag must be activated by calling `startTransaction()` with NFC enabled. `false` = Expect more commands (Default). Either set to true or false, if the NFC tag command fails, device will provide a double beep. | | encrypt | Determines if data returned is to be encrypted. `true` = Encrypt data `false` = Do not encrypt data (Default) | **Return Value:** Returns true if successful. Otherwise, returns false. ## Response Data For NFC Mifare DESFire Tag Type 4 | Tag | Len | Value / Description | | --- | --- | ------------------------------------------------------------------------------------------------ | | 81 | 02 | Tag Response (SW1 SW2). See DESFire Data Sheet (MF2DLHX0). Should follow ISO 7816-4 APDU format. | | | | · SW1 and SW2 of R-APDU | | | | If card is not able to respond: SW1 = 0x64, SW2 = 0x00 | | Tag | Len | Value / Description | | --- | --- | --- | | 821 | var | Encryption Control Payload tag data. | | | | · Data of R-APDU\*\*(see tables below)\*\* | ### ECP if unencrypted | Tag | Len | Value / Description | | ----- | --- | ------------------- | | FC | var | NFC Data Container | | /DF7A | var | NFC Data | ### ECP if encrypted: | Tag | Len | Value / Description | | ------- | --- | ----------------------------------------- | | /DFDF59 | var | Encrypted Data Primitive to be decrypted. | | /DFDF50 | var | Encrypted Data KSN | | /DFDF51 | 01 | Encrypted Data Encryption Type | #### Example Unencrypted Payload ``` 81 0100 (Tag Respons Code) 82 82036D (Encryption Control) FC 820369 (NFC Data Container) DF7A 820364 (NFC Data) 031391010F55047777772E6D616774656B2E636F6DFE00. . . www.magtek.com ``` #### Example Encrypted Payload for Fast Read ``` 81 0100 (Tag Response code) 82 820389 (Encryption Control) DFDF59 820370 (Encrypted Data Primitive) 03679DC03B4CA607E3A7D2B52C8E9F1B5CD3D85E7368425. . . DFDF50 0A (Encrypted Data KSN) FFFF9876543210200047 DFDF51 01 (Encrypted Data Type) 80 ``` ## sendPlusNFCCommand This function send a user selection to the device. ```java boolean IDevice.sendPlusNFCCommand( IData data, boolean lastCommand, boolean encrypt); ``` ### Parameter for data | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Byte 0 | Status of User Selection: `0x00` = User Selection Request completed, see Selection Result `0x01` = User Selection Request aborted, cancelled by user `0x02` = User Selection Request aborted, timeout | | Byte 1 | The menu item selected by the user. This is a single byte zero based binary value. | **Return Value:** Returns true if successful. Otherwise, returns false. ### sendSelection This function send a user selection to the device. ```java boolean IDevice.sendSelection(IData data); ``` ### Parameter for data | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Byte 0 | Status of User Selection: `0x00` = User Selection Request completed, see Selection Result `0x01` = User Selection Request aborted, cancelled by user `0x02` = User Selection Request aborted, timeout | | Byte 1 | The menu item selected by the user. This is a single byte zero based binary value. | **Return Value:** Returns true if successful. Otherwise, returns false. ### startTransaction This function starts a transaction. This function will automatically handle the opening and closing of a device. The transaction will be processed through multiple calls to the event `OnEvent`. See EMV Transaction Flow for how to process an EMV transaction. ```java boolean IDevice.startTransaction(ITransaction transaction); ``` ### Parameter | Parameter | Description | | ----------- | ----------------------------------------------------------- | | transaction | An interface that holds the parameters for the transaction. | **Return Value:** Returns true if the transaction started successfully. Otherwise, returns false. ### subscribeAll This function allows the host to be notified of all events sent by the device. ```java boolean IDevice.subscribeAll(IEventSubscriber eventCallback); ``` ### Parameter | Parameter | Description | | ------------- | ------------------------------------------------------------------------------------------- | | eventCallback | Name of a class or structure that implements the IEventSubscriber Delegate interface event. | **Return Value:** Returns true if successful. ### unsubscribeAll This function allows the host to no longer receive any events sent by the device. ```java boolean IDevice.unsubscribeAll(IEventSubscriber eventCallback); ``` ### Parameter | Parameter | Description | | ------------- | ----------------------------------------------------------------- | | eventCallback | Name of a class or structure that implements the interface event. | **Return Value:** Returns true if successful. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/android/idevice.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.