STS’ family of G8 payment applications are middleware components that sit between the Point of Sale (POS), card reader terminal and an EFT system such as that provided by a Payment System Provider (PSP). When the POS requests a card payment is made, G8 manages the card transaction process, using the card reader to read card data, and making requests to the EFT system for (optionally) BIN range information, authorisation and to provide settlement data.
G8 has a number of interfaces to existing PSPs, typically centred around messaging over HTTP or other TCP/IP protocols, as well as offline-only capability. These types of integration are used when setting up new payment solutions, or integrating with existing PSPs who already provide authorisation and settlement interfaces.
This article is intended for another class of integrator: an existing payment application provider. Such a provider may already have invested heavily in their card payments functionality – BIN range lookups, integrations to PSPs, offline capability and so on – but perhaps are only able to support one or two device types or P2PE systems, or might want to make use of G8’s clean and functional POS interface. A payment application provider might not want or need to provide a new message-based EFT system interface for G8 to use. For these providers, G8 provides an “External EFT” programmatic API, which is described in more detail below.
Functions of the EFT system
A provider who implements the External EFT API has to fulfil three functions: it must be able to provide “validation data” for PAN keyed entry (PKE) or magnetic stripe (MSR) card data, which tends to involve BIN range lookups; it must be able to request online authorisation for MSR, PKE, EMV (Chip-and-PIN) and contactless cards; and it must be able to safely store settlement data for completed transactions, and send that settlement data to PSPs or acquirers.
Implementing the External EFT API
As an integrator who wishes to provide external EFT functions, you must implement the sts.g8way.api.eft.EFTService interface. The interface has five methods: getValidationData(), getAuthorisation(), doReversal() and postTransaction(). Each method takes two parameters: a request object and a response object.
Each request object contains the relevant parameters for the request, including transaction identifiers, capture type and card details and terminal configuration. These interfaces may be extended at any time (with additional methods, or with additional enumeration values), though methods will not be redefined, and STS will ensure that the way new values are added will not prevent existing functionality from continuing to work, as long as you ensure that your implementations reject unknown enumeration values.
Each response object has methods that are used to set various response values. The EFT server “fills in” the response with the values received from upstream. Some methods are clearly marked in documentation as mandatory, which means that they must be filled in. We have chosen to implement responses in this way so that we can add new (optional or feature-specific) methods at any time without disrupting existing integrations, or requiring a complex hierarchy or versioning of response interfaces.
Validation data
This function of the EFT service is perhaps the least “standard” amongst EFT systems. G8 calls getValidationData() for magnetic stripe and PKE transactions, so that it can understand how to treat the card. G8 can also be configured to call this method for EMV transactions, but not for contactless.
For magnetic stripe cards, the EFT service has to:
Decode the magnetic stripe data, to extract the PAN and expiry data.
Examine the track’s service code to determine whether the card has a chip (if it does, G8 will request that the card be dipped, or if it has already, it will continue the transaction as a technical fallback transaction).
Look up the PAN in an IIN table to determine whether the card should continue to be processed, what card name to print on receipts, what floor limit to use and so on.
Determine the cardholder verification method to use for this card (typically the choice of whether to use signature or online PIN is set by your acquirer).
For PAN Keyed Entry, G8 calls getValidationData() after the PAN and expiry date have been entered. The EFT service has to:
Look up the PAN in an IIN table to determine whether the card should continue to be processed, what card name to print on receipts, what floor limit to use and so on
Determine whether the operator needs to enter a Start Date, Issue Number or CVV2, and what length these fields are.
For ICC, the EFT service can just accept all cards, or else use BIN ranges to determine whether the card should be processed. Typically, EMV processing is all that is required to determine the card scheme and whether it can be accepted. The EFT service can also do a hotcard list / exception file lookup, as this can be used to affect the rest of the EMV transaction.
Authorisation
G8 will call getAuthorisation() if previous processing has determined that online authorisation is required. The EFT service should construct an authorisation message, send it to the acquirer and plug the result into the authorisation response object. The EFT service might also be capable of performing some sort of stand-in processing in the case of communications failures, for example.
Reversal
G8 will call doReversal() if it has previously called getAuthorisation(), and that method indicated either an approval or an error, and the transaction is subsequently declined (for example, by a signature check or another failure). The EFT service should attempt to reverse the transaction if it can – the exact mechanism depends on the acquirer’s rules.
Post-transaction
G8 will call postTransaction() if getAuthorisation() has previously been called, plus for every offline-authorised or offline-declined transactions. The request contains the transaction outcome (approved, declined, error, cancelled), plus transaction details. The EFT service must store or transmit these details for approved transactions – G8 will not store the transaction data elsewhere, and will not call this method again.
If the EFT service fails to transmit data, and can’t store it either, it must throw an exception; G8 will then report this failure to the cardholder and the merchant, and will print void receipts as necessary.
Tell G8 to use the External EFT
To pass this to a G8:Client instance, you must use the G8way Builder API, and call G8wayBuilder.setExternalEFT() before calling createG8way().
To pass it to a G8:Enterprise instance, you can call G8wayController.addExternalEFT(), passing a name and the EFTService instance. You must then use the G8wayController configuration API to use that instance for new G8 instances, or you must already have configured G8wayController to use that name for all new G8 instances.
Note that with G8:Enterprise, the EFT Service instance will be shared amongst multiple G8 instances, all running transactions at the same time. Any of the methods of EFTService may be called in parallel from multiple threads at the same time.
Shutdown
When G8:Client (created using a G8wayBuilder) is shut down, it will call shutdown() on your EFT service instance. You can clear up any resources that are no longer required. G8 will not use the EFT service after this point.
With G8:Enterprise, shutdown() is only called when the EFTService goes out of use completely. This occurs when G8:Enterprise is shut down, or when the service is removed by calling G8wayController.removeEFTService().
Conclusion
With the External EFT system, STS have added further flexibility to G8. Existing card payment applications can continue to use their own payment features (reporting, offline processing and resiliency, alternative card types) whilst leveraging G8’s best features: support for many card reader device types, multiple P2PE scheme support, plugins, clean and powerful POS API and varied deployment models. Point-of-Sale systems and merchants integrated to G8 now have more choice of payment system provider, as well as STS’ long-standing support of devices, P2PE schemes and plugins.