G8 on Android

STS’ G8 EFT Client is now confirmed to be usable on Android, with a few new features to help integrators with that process. Here, we explain these new features, provide some guidelines for using G8 on Android, and explain what devices are compatible.

G8 is written in Java, which provides, among many other benefits, cross-platform compatibility: STS software runs on 32-bit and 64-bit Windows, Windows CE, various Linux flavour and IBM 4690. The Android operating system incorporates the Dalvik VM, which runs Java code. Using such Java code is the recommended way of developing Android applications. The Android VM provides all of the core Java libraries, plus its own libraries for user-interface phone- or tablet-specific features, but does not include some optional Java libraries. In principle, any Java library that does not use any of the optional libraries, like G8, can be re-used without changes, but there are some additional practical considerations.

New G8 features for Android

G8 Builder

G8 reads configuration files, stores transaction data and can write log files. In most environments, these files can be specified relative to the current working directory, or else the integrator can have complete control over where G8 is installed, and can configure G8 accordingly. Under Android, the location of an applications designated storage folder, and the locations of external storage folders are only really discoverable at runtime by the application itself. Additionally, all applications are started with the current working directory set to the root folder. This means that it is not generally possible to pre-configure properties files with file locations.

Applications could load properties template files, edit any properties that relate to file locations, save the files again, then start G8 with those properties files. To avoid this palaver, the G8 Builder API introduced for G8:Link has been extended to allow G8 configuration to be provided programmatically: an application has to load properties files and edit any properties that relate to file locations, but can then pass them to the G8 Builder, which will use them directly.

This addition to the G8 Builder API may also come in handy for other integrators who want to customise G8 configuration programmatically, for example, for providing the locations of downloaded blacklist files.


The G8 SDK now includes two new Jar files: G8wayAndroidAPI and G8wayAndroid; these aggregate most of the components of G8 into simple Jars, removing problematical and unusable components. Integrators can use these two Jars (plus an appropriate EMV Kernel Jar) without having to include any selection of Jars from the main G8 SDK.

There are two separate Jars to provide support to Xamarin developers. Xamarin is a cross-platform mobile application development environment that allows developers to develop in .NET languages for various mobile platforms. Xamarin applications run in a Mono-derived virtual machine that is separate from the Dalvik VM, but can use Java APIs via a wrapper system. Xamarin developers must create these wrappers for APIs that they are interested in, but creating wrappers for the entire G8 distribution is difficult and unnecessary. The G8wayAndroidAPI Jar contains only the G8 API: Xamarin developers can create wrappers for the G8wayAndroidAPI Jar, and include G8wayAndroid when building the Android APK.

Using G8 on Android

G8 development on Android (in Java) follows the same pattern as any other Java integration to G8. The G8 Integration Guide provided as part of the SDK includes a walk-through of basic features, and descriptions of all the major G8 features, and the SDK also includes a Javadoc reference guide to the whole API.

G8 has a number of background processes for trickle-feeding settlement files and related items, and control of any devices. Processing a transaction may also require writing the settlement file to disk. These processes deal with non-atomic file-writing. Android applications can be spontaneously killed by the operating system when they are in certain states. Therefore, it may be advantageous to separate use of G8 into a Service that will only be destroyed when it is no longer used. The onDestroy() method should be implemented to cleanly shut down G8.


G8 on Android supports any IP-based devices that G8 supports such as Ingenico devices including the iSMP and iCMP and Verifone IP-based devices. STS plan support for Bluetooth devices such as the VeriFone Vx600 and other devices intended for use with tablets.


G8 may now be deployed on Android devices alongside Windows, Linux, IBM 4690, Windows CE, Windows Mobile. On each of these platforms, G8 supports card readers from Ingenico, Verifone and many other manufacturers. Merchants might want to complement existing Point-of-Sale systems with tablet / card-reader combinations for queue-busting or just for in-store flexibility.

G8, offline only

STS’ G8 products are designed to be used in many different environments. This article examines G8’s capability in offline-only environments, where there is no possibility to perform online authorisation, and limited connectivity for sending settlement files; for example, on board aircraft, trains or buses, or in unconnected, unattended terminals like vending machines or car park terminals.

G8 is also usable in situations with limited or transitory connectivity for online authorisations, such that it can authorise transactions offline after trying and failing to get online authorisation. Though it is not the main subject of this article, many of the same concepts apply.


Offline processing is covered by many different rules from different sources (EMV, the Schemes) as well as the merchant’s preferences towards transaction flow and risk. If merchants follow Scheme and EMV rules for both chip cards and magnetic stripe cards then they do not take on much risk, but may be forced to reject cards that could otherwise have been used. MasterCard does have some specific rules that allow a merchant to accept some cards even if EMV processing would have declined them but some cards will still be rejected; if the merchant wishes to reject fewer cards, then they must do so with the cooperation of their acquirer, and generally have to take on the risk for fraudulent transactions.

Configuring G8 for offline processing therefore covers many different aspects of transaction processing: the transaction flow, EMV configuration, EFT configuration, BIN range and blacklist file and the settlement process. These aspects are examined in more detail below.

EFT system

The G8 EFT system consists of a number of different drivers that allow transaction data to be sent to different PSPs (Payment Service Providers, or Processors) for processing. While the communication protocol is different for all of these drivers, they are configured in the same way to support offline authorisation. They can also all store settlement data locally to be sent to the PSP when possible (see Settlement, below).

Offline-only systems can still use any of the G8 EFT drivers. Offline-only drivers such as apacs29sts.fileOnly cannot support online authorisation. Other drivers that can support online authorisation should be configured with an invalid host (for example, a hostname defined by the relevant standards to be invalid, such as “eft.invalid”) for validation and authorisation; this will cause them to fall back to offline processing magnetic stripe transactions.

An EMV kernel configured as an offline-only Terminal Type will never request online authorisation, and transactions will be authorised offline according to EMV and scheme rules: see EMV configuration, below, for more details.

If the merchant is accepting magnetic stripe transactions, they need to configure G8’s offline BIN ranges and blacklist. There are a number of trade-offs between fraud risk, unnecessarily rejected transactions and PCI compliance that have to be balanced by the integrator on behalf of the merchant. See Offline magnetic stripe authorisation.

EMV configuration

Configuration for offline-authorised EMV transactions is configured in terminal.emv.properties, whether you are using the Emvelink EMV Kernel or another kernel such as Ingenico RAM. Details may be found in the Emvelink Configuration Guide. Typically the basic configuration options will be provided by the acquirer: there will be specific settings for Terminal Type (21) and Terminal Action Codes and Floor Limits, as well as the usual settings for Certificate Authority keys. The EMV Kernel manufacturer will have specific EMV L2 approvals, and you must choose the Terminal Type and Terminal Capabilities from those approved kernel configurations.

MasterCard “on-board” processing

For deployment scenarios that count as “on-board”, the terminal can be configured to accept certain EMV cards that would otherwise be rejected. On-board terminals are those used on trains or buses or in similar scenarios. You must consult your acquirer before activating this setting. The on-board rules allow the terminal to accept a MasterCard card as long as PIN verification was successful, and the transaction was approved by the terminal but declined by the card. Typically this applies to cards that have internal counters that indicate that they have done too many offline authorisations and now require an online authorisation.

On-board processing actually applies to both online-capable and offline-only terminals, though the rules do differ slightly. On-board rules are activated in the same way whether the terminal is online-capable or offline-only.

On-board processing is activated by setting byte 1 bit 1 of tag DF54 (Payment System Specific Settings) in terminal.emv.properties. Consult the Emvelink Configuration Manual for more details.

Accepting more cards

Most modern EMV cards have internal counters that ensure that they gain online authorisation regularly, to allow the Schemes and issuers to manage fraud more effectively; generally, once some limit has passed, these cards will request online authorisation and will decline if it could not be achieved. Some cards, such as Maestro or Visa Debit cards always require online authorisation. In an offline-only environment, these cards will always be declined, which may be frustrating for the cardholder, and may lead to loss of sales for the merchant.

Generally merchants do not take on liability for transactions that were accepted according to the Scheme rules, even if those transactions turn out to be fraudulent. Some merchants may wish to take on liability for accepting fraudulent transactions, in return for being able to accept these cards. Examples of this may be the ability to accept all cards that have passed Data Authentication and Cardholder Verification (i.e. those that are cryptographically shown to be secure, and for which the cardholder knows the PIN), or just cards below some limit, or by forcing a voice-referral for particular cards, or some combination. G8 supports all of these possibilities; consult the Emvelink Configuration Manual or contact STS Support for more details.

Contactless configuration

Offline-only contactless configuration is straightforward: an appropriate certified kernel configuration must be chosen, and touchlink.emv.properties must be configured with parameters received from the acquirer. As there is no possibility of performing online authorisation, more transactions than usual will fall-forward to full EMV processing.

Offline magnetic stripe authorisation

In EMV-enabled regions of the world, Scheme rules require that all magnetic-stripe transactions are authorised online. Authorising magnetic stripe transactions in an offline-only environment typically requires that the merchant takes on liability for all magnetic-stripe transactions approved offline. Additionally, Scheme rules or merchants may require that EMV-capable cards cannot be accepted using magnetic stripe.

Configuration for offline processing of magnetic stripe transactions is therefore almost entirely driven by the merchant’s appetite for fraud risk versus lost sales.

If the merchant does wish to accept magnetic stripe transactions, there are two primary configuration files that they can use to manage risk: offline BIN (IIN) range files, and a card blacklist (also known as hotcard or exception file).


It is typical for offline-only terminals to disallow fallback – that is, to prevent cards that have an EMV chip from being accepted in “fallback” or “downgraded” mode, using the track 2 data. This is configured in G8’s tender.properties; consult the G8 Configuration Guide for more details.

BIN ranges

In online-capable scenarios, G8’s offline BIN range file is typically very simple, just providing different information for different card schemes; all transactions will be authorised online anyway. In offline-only terminals, the offline BIN range file is likely to be very detailed, with several thousand entries, based on up-to-date BIN range files from the acquirer or another provider. These files allow the merchant to accept only cards that are in ranges that are in active use by issuers.

G8’s binary BIN range format allows extremely large BIN range tables to be configured and used even on low-powered devices. The BIN range file is not loaded into memory, but is efficiently queried on disk; this means that G8 does not use much RAM for the BIN range file, but still performs lookups in fractions of a second.

Offline BIN range files are typically generated by first creating a (human-readable) “BIN-range feed-in file” and a “profile file”. The profile file defines various card profiles (i.e. MasterCard, Maestro or Visa cards). The feed-in file defines all of the configured BIN ranges, and indicates which profile each range applies to. Before use in G8, the feed-in file must be converted into the binary format using a tool provided with the G8 SDK. See the “G8 Configuration Manual” for more details.

The BIN range file may be used in conjunction with the hotcard file to reject individual cards.

Blacklist/hotcard/exception file

Blacklist files are distributed by various providers with varying numbers of listed cards. The most detailed files may contain around 3 million entries. Additionally, there is a PCI-DSS-compliance angle to blacklist files, as the card numbers listed in them are actually real card numbers, and therefore count as sensitive authentication data.

G8 has a binary file format that allows such large files to be stored and queried efficiently on disk, without using large amounts of RAM and without storing plaintext card numbers. The blacklist file is an oracle, constructed by storing only hashed card numbers; when a card is looked up, it is first hashed, and then the hash is searched-for in the file. If the hash is present, then the card is on the blacklist; the hash algorithm ensures that the likelihood of collisions and false-positives are negligible.

There is a security trade-off between speed of access and file security. In order that the fast lookup can be performed, all PANs in a single blacklist file have the same salt. This means that each file is susceptible to certain recovery techniques. Therefore, we recommend that you use an extremely large salt, and that the PANs are randomly distributed across multiple files each with a different salt. The trade-off is that the processing time to determine that a card is not on the blacklist will scale linearly with both the salt length and the number of files, but only logarithmically with the size of each file. Integrators should ensure that they tailor the salt size and the number of files to the capabilities of the deployment environment, whilst maintaining a reasonable barrier to recovery of all PANs in the file.


In an offline-only scenario, settlement data must still be transmitted to the PSP when possible. This process may take a number of forms:

The apacs29sts.fileOnly driver writes an APACS 29STS-formatted file that the integrator’s systems must process and transmit.

Other EFT drivers will transmit data when triggered

Online-capable EFT drivers can constantly attempt to transmit data, such that settlement data will automatically be sent when connectivity is established

To trigger file creation or a transmission process, the integrator must use the Settlement API. The Settlement API allows the process to be triggered, and the result of that process to be examined. The API will report if there are any errors in stored files or the transmission process (for whatever reason).


Most G8 drivers store settlement card data encrypted using a public key (or using a symmetric key itself encrypted using a public key). The private-key counterpart is stored remotely by the EFT server, and is never downloaded to G8. This means that the card data cannot be recovered using information held by G8. G8 only stores the data required for authorisation, and does not store sensitive authentication data after authorisation.

Track 2 data can be stored encrypted if the EFT server supports a process whereby magnetic stripe cards are authorised post-hoc before being settled; this technique is used to reduce the number of chargebacks a merchant may receive for fraudulent transactions, meaning that the merchant’s costs are reduced to just the lost goods or services. The use of this must be balanced against the risks of storing track data.


STS’ G8 EFT client provides an integrator or merchant with the tools required to accept transactions in offline-only deployments, supporting all the major card brands. It supports MasterCard rules to allow merchants to accept transactions in on-board scenarios, and allows merchants to balance their exposure to risk against rejection of legitimate cards according to scheme rules. Merchants can continue to benefit from G8’s support for multiple card readers, multiple PSPs, P2PE, plugins and other features.

Wednesday, December 10, 2014