Taking payments with G8

This product snippet is adapted from the comprehensive documentation that is available in the G8 SDK.

The G8 API is designed to be a simple but powerful interface for controlling all aspects of the payment system. Here, we show how, with just a few lines of code, it is possible to perform typical tasks like starting up G8 to take a payment. If you require more control over the tender process, more flexibility in transaction flow, more information about the status of the transaction or even control over the payment device or messaging to the EFT service, then G8’s flexible API makes that easy.

G8 and its API are developed in the Java programming language. If you are a Java developer, you will find that many of the concepts described in this guide will be familiar to you.

G8 also supports a .Net Interface, which is very similar to the Java API and is described in full in the G8 Programming Guide.

Start-up and Initialisation

G8 is started by creating an instance of G8way (typically at start-up along with the initialisation of the POS application). Here is an example showing G8 being created in the class constructor:

import sts.g8way.api.G8way;
import sts.g8way.api.G8wayStartupException;
 
public class ExampleClass {

  public ExampleClass() {
    try {
      G8way myG8way = G8way.createInstance();
    } catch (G8wayStartupException ex) {
      // This could have happened for a number of reasons – for example,
      // if configuration was incorrect, or if card reader hardware
      // was not detected.
 
      // <POS-SPECIFIC ERROR HANDLING LOGIC HERE> for example:
      ex.printStackTrace();
      System.exit(1);
    }
  }
}

Taking a Payment

When taking a payment with G8, you will generally do (at least) the following:

1. Create a new Tender instance.
2. Set the Tender details such as the amount being tendered.
3. Register a ReceiptHandler – during tender processing, G8 will need to print both the cardholder and the merchant’s receipt. The receipt printer hardware device is typically located on the till and controlled by the POS application. This event handler is called by G8 to trigger receipt printing at the appropriate stage during tender processing. If the card reader has a printer, G8 can use that instead; the POS can too, using G8’s APIs.
4. Register an AttendantActionHandler – during tender processing, G8 may need the attendant to perform certain actions such as verifying the cardholder signature, or performing a voice referral. This event handler is called when such an action is required.
5. Invoke the Tender processing.

The pay() method of the following ExampleClass shows how to process a basic payment for £10.00 (note that this class implements the ReceiptHandler and AttendantActionHandler interfaces):

import sts.g8way.api.*;
import sts.g8way.api.event.*;
 
public class ExampleClass implements ReceiptHandler, AttendantActionHandler {
 
  private G8way myG8way;
 
  public ExampleClass() throws G8wayStartupException {
    myG8way = G8way.createInstance();
  }
 
  public void pay() {
    // Create the tender which will process the payment, and set the amount
    Tender tender = myG8way.createTender();
    tender.setAmount(1000);   /* 10.00 GBP */
 
    // Register the necessary handlers and listeners
    tender.setReceiptHandler(this);
    tender.setAttendantActionHandler(this);
 
    // Now ready to take the payment
    TenderResult result = tender.process();
 
    // The result would typically be examined in more detail here
    if (result.isApproved()) {
      System.out.println("Tender was approved");
    } else {
      System.out.println("Tender was not approved");
    }
  }
 
  public void printReceipts(ReceiptPrintingRequest r) {
    // The POS application will typically operate the printer hardware here,
    // this is an example for illustration purposes only
    System.out.println(r.getCardholderReceipt());
    System.out.println(r.getMerchantReceipt());
  }
 
  public boolean checkSignature(AttendantActionRequest r) {
    // The attendant would typically be prompted to verify the signature
    // here - this example hardcodes the signature check result to true
    return true; /* Indicating signature was verified and valid */
  }
 
  public String doReferral(AttendantActionRequest r) {
    // The attendant would typically be prompted to perform voice referral
    // here - this example hardcodes the referral result to 'approved'
    return "12345";  /* Voice referral approved with auth code '12345' */
  }
}

How it works

Under the hood, G8 will be performing all the required transaction processing, such as: waiting for the cardholder to present a payment card; displaying user messages on the card reader hardware (e.g. “INSERT CARD”, “ENTER PIN”); for a chip-and-PIN card, triggering all required card processing in accordance with EMV specifications; connecting to the acquiring bank to get authorisation for the payment and submitting the transaction for settlement.

This example shows only the most basic scenario treating G8 essentially as a black-box payment engine. It is however possible to gain much finer-grain control over the operation of G8 such as monitoring transaction progress (e.g. when a card is inserted; when the cardholder is performing PIN entry etc.); examining transaction processing data; examining application data read from an EMV chip-and-PIN card; directly controlling the card reader hardware and more. To understand how transaction processing works in more detail and for the full list of supported functionality you should refer to the documentation included in the G8 SDK.

Conclusion

The powerful G8 API removes the complexity of integrating to card readers and payment service providers, making life easier for systems integrators and POS application developers and shortening project implementation timescales. The flexibility of the interface allows a very wide variety of transaction processing scenarios and workflows to be supported out of the box without the need for any bespoke development. Transaction processing rules are handled by G8 allowing the payments complexity to be shielded from the POS application. A consistent interface is presented to the POS even if payment specifications change over time. The G8 SDK provides more comprehensive documentation and this is the recommended next step for developers looking for greater detail on how to integrate with G8.