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.

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 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 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.

HAL architecture — how these interfaces fit together.
Implement the hardware services — the calls that exercise most interfaces above.
EMV state machine — the flow built on IEMVInterface.