> 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/java/idevice.md).

# IDevice

Create an instance of the IDevice from CoreAPI.getDeviceList(). Then use the functions described in this chapter.

### cancelTransaction <a href="#id-4.1_canceltransaction" id="id-4.1_canceltransaction"></a>

This function cancels a transaction. A transaction can only be canceled before a card is presented.

{% code overflow="wrap" %}

```
boolean IDevice.cancelTransaction();
```

{% endcode %}

Return Value:

Returns true if successful. Otherwise, returns false.

### getCapabilities <a href="#id-4.2_getcapabilities" id="id-4.2_getcapabilities"></a>

This function retrieves the IDeviceCapabilities interface to the device.

{% code overflow="wrap" %}

```
IDeviceCapabilities IDevice.getCapabilities();
```

{% endcode %}

Return Value:

Returns IDeviceCapabilities

### getConnectionInfo <a href="#id-4.3_getconnectioninfo" id="id-4.3_getconnectioninfo"></a>

This function retrieves the connection information of the device.

{% code overflow="wrap" %}

```
ConnectionInfo IDevice.getConnectionInfo();
```

{% endcode %}

Return Value:

Returns ConnectionInfo

### getConnectionState <a href="#id-4.4_getconnectionstate" id="id-4.4_getconnectionstate"></a>

This function retrieves the connection state of the device.

ConnectionState IDevice.getConnectionState();

Return Value:

Returns ConnectionState

### getDeviceControl <a href="#id-4.5_getdevicecontrol" id="id-4.5_getdevicecontrol"></a>

This function retrieves the device control interface to the device.

{% code overflow="wrap" %}

```
IDeviceControl IDevice.getDeviceControl();
```

{% endcode %}

Return Value:

Returns IDeviceControl

### getDeviceConfiguration <a href="#id-4.6_getdeviceconfiguration" id="id-4.6_getdeviceconfiguration"></a>

This function retrieves a device configuration interface to the device.

{% code overflow="wrap" %}

```
IDeviceConfiguration IDevice.getDeviceConfiguration();
```

{% endcode %}

Return Value:

Returns IDeviceConfiguration

### getDeviceInfo <a href="#id-4.7_getdeviceinfo" id="id-4.7_getdeviceinfo"></a>

This function returns an information class of the device.

{% code overflow="wrap" %}

```
DeviceInfo IDevice.getDeviceInfo();
```

{% endcode %}

Return Value:

Returns DeviceInfo

### Name <a href="#id-4.8_name" id="id-4.8_name"></a>

This function retrieves the name of the device.

{% code overflow="wrap" %}

```
String IDevice.Name();
```

{% endcode %}

Return Value:

Returns a string containing the device name.

### requestPIN <a href="#id-4.9_requestpin" id="id-4.9_requestpin"></a>

This function prompts the user to enter a PIN on the device. The response data will be returned in the event OnEvent. requestPin() is reserved for future use.

{% code overflow="wrap" %}

```
boolean IDevice.requestPIN(PINRequest pinRequest);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="130.18182373046875" valign="top"></th><th width="94.81817626953125" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Type</td><td valign="top">Description</td></tr><tr><td valign="top">Timeout</td><td valign="top">byte</td><td valign="top">Wait time in seconds.</td></tr><tr><td valign="top">PINMode</td><td valign="top">byte</td><td valign="top"><p>PIN mode.</p><p>Usage:</p><ul><li>0x00 - Enter PIN</li><li>0x01 - Enter PIN Amount </li><li>0x02 - Reenter PIN Amount </li><li>0x03 - Reenter PIN</li><li>0x04 - Verify PIN</li></ul></td></tr><tr><td valign="top">MinLength</td><td valign="top">byte</td><td valign="top">Minimum length of accepted PIN (>= 4).</td></tr><tr><td valign="top">MaxLength</td><td valign="top">byte</td><td valign="top">Maximum length of accepted PIN (=&#x3C; 12).</td></tr><tr><td valign="top">Tone</td><td valign="top">byte</td><td valign="top"><p>Tone to play when prompting for the PIN. Usage:</p><ul><li>0x00 - No sound </li><li>0x01 - One beep </li><li>0x02 - Two beeps</li></ul></td></tr><tr><td valign="top">Format</td><td valign="top">byte</td><td valign="top">ISO format for the PIN block.</td></tr><tr><td valign="top">PAN</td><td valign="top">String</td><td valign="top">The left most 12 digits of the Primary Account Number. Leave blank if not required by the ISO format for the PIN block.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

### requestSignature <a href="#id-4.10_requestsignature" id="id-4.10_requestsignature"></a>

This function prompts the user to enter a signature on the device. The response data will be returned in the event OnEvent.

{% code overflow="wrap" %}

```
boolean IDevice.requestSignature();
```

{% endcode %}

Return Value:

Returns true of successful. Otherwise, returns false.

### sendAuthorization <a href="#id-4.11_sendauthorization" id="id-4.11_sendauthorization"></a>

This function sends the Authorization Response Code (ARPC) blob to the device. The response data will be returned in the event OnEvent.

{% code overflow="wrap" %}

```
boolean IDevice.sendAuthorization(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="148.09088134765625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Contains ARPC blob.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

### sendSelection <a href="#id-4.12_sendselection" id="id-4.12_sendselection"></a>

This function send a user selection to the device.

{% code overflow="wrap" %}

```
boolean IDevice.sendSelection(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="188.09088134765625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter for data</td><td valign="top">Description</td></tr><tr><td valign="top"><p> </p><p>Byte 0</p></td><td valign="top"><p>Status of User Selection:</p><ul><li>0x00 = User Selection Request completed</li><li>0x01 = User Selection Request aborted, cancelled by user </li><li>0x02 = User Selection Request aborted, timeout</li></ul></td></tr><tr><td valign="top">Byte 1</td><td valign="top">The menu item selected by the user. This is a single byte zero based binary value.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

### startTransaction <a href="#id-4.13_starttransaction" id="id-4.13_starttransaction"></a>

This function starts a transaction. The transaction will be processed through multiple calls to the event OnEvent.

{% code overflow="wrap" %}

```
boolean IDevice.startTransaction(ITransaction transaction);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="132.9090576171875" valign="top"></th><th width="102.00006103515625"></th><th></th></tr></thead><tbody><tr><td colspan="3" valign="top">ITransaction</td></tr><tr><td valign="top">Parameter</td><td><p>Type/</p><p>Format</p></td><td>Description</td></tr><tr><td valign="top">Timeout</td><td>byte</td><td><p>Transaction timeout in seconds. Default is 60 seconds.</p><p> </p><p>Usage:</p><p>0 to 255 - Depending on the device, 0 means no timeout.</p></td></tr><tr><td valign="top">PaymentMethods</td><td>List of PaymentM ethod</td><td><p>List of the PaymentMethod enumeration.</p><p> </p><p>Usage:</p><p>MSR         - For magnetic stripe cards.</p><p>Contact     - For EMV chip cards.</p><p>Contactless - For NFC contactless cards.</p><p>ManualEntry - For user to manually enter transaction data without any card access.</p></td></tr><tr><td valign="top">QuickChip</td><td>bool</td><td><p>In QuickChip mode, the device does not prompt for an amount. Device sends an ARQC request to the host. Device automatically populates the ARPC response data with EMV Tag 8A set to “Z3”. Card holder is prompted to remove the card. Transaction result is later determined by the processor and not by the card.</p><p> </p><p>Usage:</p><p>false - Do not enable QuickChip mode.</p><p>true - Enable QuickChip mode. Default.</p></td></tr><tr><td valign="top">EMVOnly</td><td>bool</td><td><p>Flag that determines whether or not to start an EMV transaction.</p><p> </p><p>Usage:</p><p>false - Do not start transaction if the device does not support EMV.</p><p>true - Only start transaction if the device supports EMV. Default.</p></td></tr><tr><td valign="top">PreventMSRSignatureF orCardWithICC</td><td>bool</td><td><p>Flag that determines whether or not to prompt for a signature for magnetic stripe when the transaction is from a chip card.</p><p> </p><p>Usage:</p><p>false – Do not prompt for signature.</p><p>true – Allow the prompt for a signature if requested.</p></td></tr><tr><td valign="top">SuppressThankYouMes sage</td><td>bool</td><td><p>By default, devices with a display signal the end of a transaction by briefly showing “THANK YOU,” then “WELCOME.”</p><p> </p><p>Usage:</p><p>false – Do not suppress the thank you message.</p><p>true – Suppress the thank you message.</p></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="199.27276611328125" valign="top"></th><th width="90.818115234375"></th><th></th></tr></thead><tbody><tr><td colspan="3" valign="top">ITransaction</td></tr><tr><td valign="top">OverrideFinalTransacti onMessage</td><td>byte</td><td>By default, devices with a display signal the end of a transaction by returning to the idle page and showing “WELCOME.” This parameter directs the device to show a message based on the Message ID from the command displayMessage() . This option completely overrides the device’s idle page behavior until the next transaction, power cycle, or other similar state change.</td></tr><tr><td valign="top"> </td><td> </td><td><p>Usage:</p><p>0x00 - reserved, do not use. 0x01 - “AMOUNT”</p><p>0x02 - “AMOUNT OK?”</p><p>0x03 - “APPROVED”</p><p>0x04 - “CALL YOUR BANK”</p><p>0x05 - “CANCEL OR ENTER”</p><p>0x06 - “CARD ERROR”</p><p>0x07 - “DECLINED”</p><p>0x08 - “ENTER AMOUNT”</p><p>0x09 - reserved, do not use. 0x0A - reserved, do not use. 0x0B - “INSERT CARD”</p><p>0x0C – “NOT ACCEPTED”</p><p>0x0D - reserved, do not use. 0x0E - “PLEASE WAIT”</p><p>0x0F - “PROCESSING ERROR”</p><p>0x10 - “REMOVE CARD”</p><p>0x11 - “USE CHIP READER”</p><p>0x12 - “USE MAGSTRIPE”</p><p>0x13 - “TRY AGAIN”</p><p>0x14 - “WELCOME”</p><p>0x15 - “PRESENT CARD”</p><p>0x16 - “PROCESSING”</p><p>0x17 - “CARD READ OK - REMOVE CARD”</p><p>0x18 - “INSERT OR SWIPE CARD”</p><p>0x19 - “PRESENT ONE CARD ONLY”</p><p>0x1A - “APPROVED PLEASE SIGN”</p><p>0x1B - “AUTHORIZING PLEASE WAIT”</p><p>0x1C - “INSERT, SWIPE OR TRY ANOTHER CARD”</p><p>0x1D - “PLEASE INSERT CARD”</p><p>0x1E - Null prompt (empty screen) 0x1F - reserved, do not use.</p><p>0x20 - “SEE PHONE”</p><p>0x21 - “PRESENT CARD AGAIN”</p><p>0x22 - “INSERT/SWIPE/TRY OTHER CARD”</p><p>0x23 - “TAP or SWIPE CARD”</p><p>0x24 - “TAP or INSERT CARD”</p><p>0x25 - “TAP, INSERT or SWIPE CARD”</p><p>0x26 - “TAP CARD”</p><p>0x27 - “TIMEOUT”</p><p>0x28 - “TRANSACTION TERMINATED”</p></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="195.45458984375" valign="top"></th><th width="77.45458984375"></th><th></th></tr></thead><tbody><tr><td colspan="3" valign="top">ITransaction</td></tr><tr><td valign="top">EMVResponseFormat</td><td>byte</td><td><p>The format of the EMV response.</p><p> </p><p>Usage:</p><p>0x00 – Legacy. Default. 0x01 – RFU</p></td></tr><tr><td valign="top">TransactionType</td><td>byte 1</td><td><p>EMV Tag 9C - The type of financial transaction, represented by the first two digits of the ISO 8583:1987 Processing Code.</p><p> </p><p>Examples:</p><p>0x00 – purchase. Default.</p><p>0x01 – cash advance</p><p>0x09 – purchase with cashback</p><p>0x20 – refund</p><p>Supported transaction types are specified in the commands manual specific to the device.</p></td></tr><tr><td valign="top">Amount</td><td>String 12</td><td><p>EMV Tag 9F02 - Authorized amount of the transaction.</p><p> </p><p>Example:</p><p>“000000000123” – $1.23</p><p>“000000009999” – $99.99</p></td></tr><tr><td valign="top">CashBack</td><td>String 12</td><td><p>EMV Tag 9F03 - Secondary amount associated with the transaction.</p><p> </p><p>Example:</p><p>“000000000123” – $1.23</p><p>“000000009999” – $99.99</p></td></tr><tr><td valign="top">CurrenyCode</td><td>byte[] 2</td><td><p>EMV Tag 5F2A - Currency code of the transaction according to ISO 4217. The byte array is null by default.</p><p> </p><p>Example:</p><p>0x0840 = US Dollar 0x0978 = Euro 0x0826 = UK Pound</p></td></tr><tr><td valign="top">CurrencyExponent</td><td>byte[] 1</td><td><p>EMV Tag 5F36 - The decimal point position from the right of the transaction amount. The byte array is null by default.</p><p> </p><p>Example:</p><p>0x02 – decimal point at 2 position from the right.</p></td></tr><tr><td valign="top">TransactionCategory</td><td>byte[] 1</td><td>EMV Tag 9F53 - The type of contactless transaction being performed. The byte array is null by default.</td></tr><tr><td valign="top">MerchantCategory</td><td>byte[] 2</td><td>EMV Tag 9F15 - The type of business being done by the merchant, represented according to ISO 18245. The byte array is null by default.</td></tr><tr><td valign="top">MerchantID</td><td>byte[] 15</td><td>EMV Tag 9F16 - Used to uniquely identify a given merchant. The byte array is null by default.</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="197.45452880859375" valign="top"></th><th width="104.54541015625"></th><th></th></tr></thead><tbody><tr><td colspan="3" valign="top">ITransaction</td></tr><tr><td valign="top">MerchantCustomData</td><td>byte[] 20</td><td>EMV Tag 9F7C – Proprietary merchant data that may be requested. The byte array is null by default.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

### subscribeAll <a href="#id-4.14_subscribeall" id="id-4.14_subscribeall"></a>

This function allows the host to be notified of all events sent by the device.

{% code overflow="wrap" %}

```
boolean IDevice.subscribeAll(IEventSubscriber eventCallback);
```

{% endcode %}

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">eventCallback</td><td valign="top">Name of a class that implements the IEventSubscriber Delegates event.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

### unsubscribeAll <a href="#id-4.15_unsubscribeall" id="id-4.15_unsubscribeall"></a>

This function allows the host to no longer receive any events sent by the device.

{% code overflow="wrap" %}

```
boolean IDevice.unsubscribeAll(IEventSubscriber eventCallback);
```

{% endcode %}

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">eventCallback</td><td valign="top">Name of a class that implements the IEventSubscriber Delegates event.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/java/idevice.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
