# Service Interfaces Reference

This page catalogs every AIDL interface your Manufacturer Service App can implement. It also lists the fixed values Getnet's platform expects from a few of them. For the calls that exercise these interfaces, see [Implement the hardware services](/en/pos-manufacturers/how-to-guides-pos-mfg/implement-hardware-services).

## IMainService

The entry point. The Middleware App binds to your service through the package `com.pagonxt.hal.platform.service` and gets an `IMainService` stub. It reaches every other interface through that stub.

| Accessor | Returns |
| :--- | :--- |
| `getStats()` | `IStatService` |
| `getPrinter()` | `IPrinterService` |
| `getCard()` | `ICardService` |
| `getMifare()` | `IMifareService` |
| `getBeeper()` | `IBeeperService` |
| `getLed()` | `ILedService` |
| `getInfo()` | `IInfoService` |
| `getCamera()` | `ICameraService` |
| `getEmv()` | `IEMVInterface` |

## ICardService

Handles card search across every read technology your device supports.

| Method | Description |
| :--- | :--- |
| `search(long timeout, in String[] searchType, in ICardCallback callback)` | Searches for a card using one or more of the search types below, until `timeout` elapses. |
| `stopAllReaders()` | Stops every active reader. Call it once `onCard`, `onMessage`, or `onError` fires. |

Search types:

| Constant | Value |
| :--- | :--- |
| `MAG` | `"1"` |
| `CHIP` | `"2"` |
| `NFC` | `"3"` |

`onCard` returns a `CardResponse` with `pan` (chip and NFC) or `track1` / `track2` / `track3` (magnetic stripe).

## IMifareService

Covers Mifare card presence, authentication, and block-level read/write.

| Method | Description |
| :--- | :--- |
| `searchCard(in IMifareCallback callback)` | Searches for a Mifare card. |
| `searchCardAndActivate(in IMifareActivateCallback callback)` | Searches for and activates a Mifare card in one call. |
| `activate(int cardType)` | Activates a card of the given type. |
| `halt()` | Halts the active card. |
| `getCardSerialNo(int cardType)` | Returns the card's serial number (UID) as a hex string. |
| `authenticateSectorWithKeyA(int sector, in byte[] key)` | Authenticates a sector with Key A. |
| `authenticateBlockWithKeyA(int sector, in byte[] key)` | Authenticates a block with Key A. |
| `authenticateSectorWithKeyB(int block, in byte[] key)` | Authenticates a sector with Key B. |
| `authenticateBlockWithKeyB(int block, in byte[] key)` | Authenticates a block with Key B. |
| `close()` | Closes the current Mifare session. |
| `decrement(int index, int value)` | Decrements the value block at `index` by `value`. |
| `increment(int index, int value)` | Increments the value block at `index` by `value`. |
| `isExist()` | Returns whether a Mifare card is present. |
| `readBlock(int index)` | Reads the block at `index`, returned as a string. |
| `restore(int index)` | Restores the value block at `index`. |
| `transfer(int index)` | Transfers the value block at `index`. |
| `writeBlock(int index, String data)` | Writes `data` to the block at `index`. |
| `exchangeAPDU(in byte[] apdu)` | Sends a raw APDU and returns an `APDUResponse`. |

Keys are 6 bytes. Block and sector authentication use the parameter names as declared in the AIDL above. `authenticateBlockWithKeyA`/`B` take a parameter literally named `sector`, even though it identifies a block.

## IPrinterService

Builds and prints a receipt from a queue of text, barcode, QR code, and image elements.

| Method | Description |
| :--- | :--- |
| `init()` | Initializes the printer. Every other method throws `IllegalStateException` if called before this one. |
| `getStatus()` | Returns the current printer status. |
| `setGray(int gray)` | Sets the grayscale level applied to images. |
| `addText(int align, String text)` | Queues a line of text at the given alignment. |
| `addBarCode(int align, String barcode)` | Queues a barcode. |
| `addQrCode(int align, int imageHeight, String qrCode)` | Queues a QR code at the given height. |
| `addImageBitmap(int align, in Bitmap bitmap)` | Queues a `Bitmap` image. |
| `addImageByteArray(int align, in byte[] byteArray)` | Queues an image from raw bytes. |
| `defineFontFormat(int fontFormat)` | Sets the active font. |
| `print(in IPrinterCallback callback)` | Prints everything queued. |
| `printAndRemovePaper(in IPrinterCallback callback)` | Prints everything queued, then feeds and cuts the paper. |

### Font constants

`defineFontFormat` takes one of these three constants.

| Constant | Value | Size |
| :--- | :--- | :--- |
| `FONT_12_16A` | `11` | Small |
| `FONT_16_32B` | `15` | Medium |
| `FONT_32_32B` | `22` | Large |

### Printer specifications

Fixed values and behaviors your printer implementation must follow.

| Rule | Value |
| :--- | :--- |
| Maximum image size | 378 pixels. Your service resizes larger images automatically. |
| Maximum characters per line — medium and large fonts | 32 characters. Medium and large differ only in height. |
| Maximum characters per line — small font | 48 characters. |
| Grayscale threshold | 175. Your service is responsible for the grayscale transformation. |
| Repeated `init()` calls | Must not clear the print queue. Clear it only when your service's `print()` method runs. |
| Image methods | All `addImage*` methods must accept `Bitmap` input. |
| Long text | `addText` calls exceeding the character limit must wrap automatically across multiple lines. |
| New line after queued content | Every method that queues content (text or image) must automatically append a line break. |

## IBeeperService

Plays audible feedback for cardholder and operator actions.

| Method | Description |
| :--- | :--- |
| `custom(int durationMillis)` | Plays a beep for the given duration, in milliseconds. |

Named sounds and their required duration:

| Sound | Duration |
| :--- | :--- |
| `success` | 500 ms beep. |
| `error` | 1000 ms beep. |
| `digit` | 100 ms beep. |
| `nfc` | 100 ms beep, 300 ms pause, 100 ms beep. |

## ILedService

One on/off pair per color: `turnOnRed` / `turnOffRed`, `turnOnBlue` / `turnOffBlue`, `turnOnYellow` / `turnOffYellow`, `turnOnGreen` / `turnOffGreen`.

## IInfoService

Returns device identification data. See [InfoResponse](#inforesponse) for the full field list.

## ICameraService

Reads the device's front camera for scanning use cases.

| Method | Description |
| :--- | :--- |
| `readFront(long timeout, in ICameraCallback callback)` | Reads the front camera until `timeout` elapses, or until the caller cancels the read. |

`ICameraCallback` reports `onSuccess(code)`, `onTimeout()`, `onCancel()`, and `onError(error)`.

## IStatService

Reports usage counters for card reads and paper consumption, both device-wide and per calling app.

| Method | Description |
| :--- | :--- |
| `getPaperStatus()` | Total paper consumption, device-wide. |
| `getAllAppPaperStatus()` | Paper consumption, per calling app. |
| `getMagStatus()` | Total successful magnetic stripe swipes. |
| `getAllAppMagStatus()` | Successful magnetic stripe swipes, per app. |
| `getMagStatusFail()` | Total magnetic stripe failures. |
| `getAllAppMagStatusFail()` | Magnetic stripe failures, per app. |
| `getChipStatus()` | Total successful chip insertions. |
| `getAllAppChipStatus()` | Successful chip insertions, per app. |
| `getChipStatusFail()` | Total chip insertion failures. |
| `getAllAppChipStatusFail()` | Chip insertion failures, per app. |
| `getNfcStatus()` | Total successful contactless (NFC) transactions. |
| `getAllAppNfcStatus()` | Successful contactless transactions, per app. |
| `getNfcStatusFail()` | Total contactless failures. |
| `getAllAppNfcStatusFail()` | Contactless failures, per app. |
| `getMifareStatus()` | Total successful Mifare proximity reads. |
| `getMifareStatusFail()` | Total Mifare proximity failures. |
| `getAllStatisticsByApp()` | Every success and failure count above, grouped by app. |

Several HAL methods receive a `userId` parameter identifying the calling app. Examples include `print(int userId, IPrinterCallback callback)` and `searchMag(int userId, long timeout, in ICardCallback callback)`. Resolve `userId` to a package name with `packageManager.getNameForUid(userId)` to attribute statistics correctly.

## IEMVInterface

Used through `IMainService::getEmv`. See [EMV state machine](/en/pos-manufacturers/core-concept-pos-mfg/emv-state-machine) for how these methods fit into a transaction.

| Method | Description |
| :--- | :--- |
| `create(IEMVEventsAIDL events)` | Associates an event listener with the service. Call before any transaction. |
| `reset()` | Resets every long-term parameter. |
| `version()` | Returns a `List<Version>` describing the running EMV kernel. |
| `setAIDParameter(in List<AIDParameter> data)` | Sets AID-specific parameters. Long-term, high priority except for parameters set through `setTLV`. |
| `setCAKey(in List<CAKey> data)` | Sets the certificate authority key list. Long-term, low priority. |
| `setRevoked(in List<Revoked> data)` | Sets the list of revoked certificate serial numbers. Long-term. |
| `setRiskManagement(in Risk risk)` | Sets the transaction risk management parameters. Long-term. |
| `setTLV(in List<TLV> tlvs)` | Sets a list of TLVs for the current transaction only. Short-term, highest priority. |
| `setTerminal(in Terminal terminal)` | Sets terminal data. Long-term, overwrites previously set parameters. |
| `start(in List<String> aidList, in Transaction transaction)` | Starts card data collection for a transaction. The EMV kernel ignores any AID not present in `setAIDParameter`. |
| `get(in List<String> list, IGetCallback get)` | Retrieves the requested TLVs asynchronously. |
| `getSimplified(in List<String> data)` | Retrieves the requested TLVs synchronously, returned as `List<TLV>`. |
| `cancel()` | Cancels the current EMV flow. The application must still wait for the end event before treating the transaction as canceled. |

## IMaintenanceInterface

Covers device upkeep: self-checks, remote updates, and clock settings.

| Method | Description |
| :--- | :--- |
| `setSelfTestHourRange(String min, String max)` | Sets the self-check (auto-reset) reboot window, as `"HH:mm"` strings. Returns `0` on success, `-1` on error. |
| `setAutoUpdateHourRange(String min, String max)` | Sets the auto-update attempt window, as `"HH:mm"` strings. Returns `0` on success, `-1` on error. |
| `setAutoUpdate(boolean isEnabled, boolean autoRebootEnabled)` | Enables or disables auto-update. Returns `0` on success, `-1` on error. |
| `setAllowGprsUpdate(boolean isEnabled)` | Allows or blocks remote update over 3G/4G. Returns `0` on success, `-1` on error. |
| `installApp(String filePath, IMaintenanceResult result)` | Silently installs the APK at `filePath`. Returns `0` on success, `-1` on error. |
| `uninstallApp(String packageName, IMaintenanceResult result)` | Silently uninstalls `packageName`. Returns `0` on success, `-1` on error. |
| `setTimeZone(String id)` | Sets the device time zone. Returns `0` on success, `-1` on error. |
| `setDateTime(String dateTime)` | Sets the device's local date and time, as `"YYYYMMDDHHmmss"` (for example, `"20250314093500"`). Returns `0` on success, `-1` on error. |

## IEncryptionInterface

Covers key status and data encryption for the device's key management.

| Method | Description |
| :--- | :--- |
| `getKSNbyPosition(int index)` | Returns the hex-coded KSN of the key at `index`, or an empty string if none exists. |
| `injectWorkingKey(int index, int mkIndex, in byte[] keyBlock)` | Injects a working key at `index`, encrypted by the master key at `mkIndex`. |
| `encryptData(int index, int method, in byte[] plainText)` | Encrypts `plainText` with the key at `index`. `method` is `1` for CBC mode or `2` for EBC mode, as documented in the manufacturer kit. Returns the encrypted data, or `null` on error. |

## InfoResponse

Fields returned by `IInfoService` and related device-info calls:

| Field | Description |
| :--- | :--- |
| `sdkVersion` | Version of the installed SDK. |
| `bcVersion` | Version of the boot/base component. |
| `osVersion` | Operating system version. |
| `serialNumber` | Device serial number. |
| `psamId` | PSAM identifier. |
| `model` | Device model. |
| `manufacture` | Device manufacturer. |
| `imsi` | SIM IMSI, if present. |
| `imei` | Device IMEI. |
| `iccid` | SIM ICCID, if present. |
| `romVersion` | ROM version. |
| `androidKernelVersion` | Android kernel version. |
| `androidOSVersion` | Android OS version. |
| `hardwareVersion` | Hardware revision. |
| `firmwareVersion` | Firmware version. |
| `hardWareSn` | Hardware serial number. |

## Related resources

* [HAL architecture](/en/pos-manufacturers/core-concept-pos-mfg/hal-architecture) — how these interfaces fit together.
* [Implement the hardware services](/en/pos-manufacturers/how-to-guides-pos-mfg/implement-hardware-services) — the calls that exercise most interfaces above.
* [EMV state machine](/en/pos-manufacturers/core-concept-pos-mfg/emv-state-machine) — the flow built on `IEMVInterface`.