Offline Mode


Considering the nature of the Payment Processing, it's reasonable to think that in some cases, physical connectivity issues impose obstacles to online transactions, and that might not be in the best interest of Merchants, once it can result in lost sales.

Connectivity problems may become a great treat to a Merchant that deals with “Present Card Holder” transactions.

Let’s take as an example a fast-food Merchant: while dealing with the sales on a balcony, if for any reason the Merchant can’t process online payments – bad or slow connection, for instance – this Merchant's clients will most probably choose another option to eat, and the longer this problem remains, the bigger is going to be the loss.

A solution for that would be allowing the Terminal, in which the transaction is executed, to work offline.

The Offline Mode solution allows any payment terminal to be managed to guarantee that whenever the connectivity with the gateway is “Healthy”, the transaction goes to the payment gateway, and when is not “Healthy”, you can retrieve and store the transaction and sent it whenever the connectivity is “Healthy” again.

To enable solutions, using CoChip, to be able to manage this scenario, a set of new features were developed, and the next sections are going to guide you about their use.

PREREQUISITES

Remember that regardless of the option you choose, the steps described here must be done only after the necessary steps from Getting Started are also done.


Introduction

The main concept you need to understand here is simple: when a Terminal works in Offline Mode, the transactions executed using this Terminal won’t be sent to the Payment Gateway, as usually does (Figure 1).

 Figure 01 - Common Flow

Instead, those transactions will be sent back to Your Solution (Figure 2).

 Figure 02 - Offline Mode - Executing Offline Sales

After that, whenever is convenient to Your Solution, you can send the Offline Transactions to the gateway (Figure 3) and treat the response to they went through.

 Figure 03 - Offline Mode - Sending Offline Sales

With this new flow possibility, your Terminals will be able to work offline without losing sales even when there’s no connectivity to the Gateway.

But to do this, first Your Application needs a few changes, like setting up terminals allowed to work offline, treat the offline responses and send the offline responses whenever the gateway connectivity is available again.

To setup terminals to work offline, Your Solution has two options:

  1. 1. Set any Terminal to Offline Mode manually – see the section Working Offline by Choice for more details on how.
  2. 2. Inform the TerminalHealthy checker which Terminals should work on Offline Mode based in case there's no connection available with the Gateway – see section Working Offline when Necessary for more details on how it works.

For the responses, Your Application needs to add treatment for the callback defined by the CoreApiListener interface related to the Offline Sale Responses (Treating the Sale Offline Response)..

Finally, Your Application needs to implement (based on time or any other logic) a call to the gateway to send for processing all the offline responses received while terminals worked in offline mode (Sending the Offline Sales to the Gateway).

The next subsections will detail what are the considerations necessary to each form of implementing the Offline Mode on Your Solution.

Working Offline by Choice

In this scenario, you can add to Your Solution a “offline/online mode switch”, allowing to set Terminals to work in Offline Mode purposely.

To do this, all this “offline/online mode switch” needs is to call the following Terminal method:

  • AndroidTerminal.getInstance().setOfflineMode(true);

  • JavaTerminal.getInstance().setOfflineMode(true);

  • [[WTPSTerminal singleton] setOfflineMode:YES];

  • Terminal.getInstance().setOfflineMode(true);


In case your logic also needs to verify if the Terminal is operating in offline mode, you can also use the following.

  • AndroidTerminal.getInstance().getOfflineMode();

  • JavaTerminal.getInstance().getOfflineMode();

  • [[WTPSTerminal singleton] getOfflineMode];

  • Terminal.getInstance().getOfflineMode();


Those two new options were added to the Terminal class so your application can switch on and off the Offline Mode.

  • getOfflineMode(): Boolean method, which returns the offlineMode state of a specific Terminal. When returns True, means that the Terminal is in Offline Mode, otherwise returns False.
  • setOfflineMode(Boolean offline): Boolean method, which changes the Offline Mode of a Terminal depending on the value informed on the offline argument – returns True when the Offline Mode of a Terminal is successfully enabled or disabled, otherwise returns False. In some cases, a Terminal can’t be changed manually from or to Offline Mode due to some incorrect or inconsistent information that makes the terminal be invalid – null, without settings or without the server URL.

Working Offline when Necessary

In this scenario, you can enables Terminals to work on Offline Mode just when the communication with the Payment Gateway is not “Healthy”.

To do this Your Solution needs to:

Step 01. Define Your Own Settings

Configure the Terminal Healthy Controller (TerminalHealth): this implementation should be added to your main class that controls the use of all the Terminals.

  • TerminalHealth.configureTerminalHealthChecker (10000, 10000);

  • TerminalHealth.configureTerminalHealthChecker (10000, 10000);

  • [TerminalHealth configureTerminalHealthChecker:10000 withInterval:10000];

  • TerminalHealth.ConfigureTerminalHealthChecker(10000, 10000);


Although this implementation is not actually necessary, once a default configuration is already set to the TerminalHealth timeout and interval onde you starts this mode, you can define your own settings.

  • timeout: argument, in milliseconds, used to define the accepted timeout before generating an error while checking the connection’s healthy between each Terminal and the Payment Gateway. Needs to be smaller than the interval argument. It has a minimum (and default) acceptable value of 5 seconds (5000 milliseconds).
  • interval argument, in milliseconds, used to define the interval for connection’s healthy checking between each Terminal and the Payment Gateway. Needs to be bigger than the timeout argument. It has a minimum (and default) acceptable value of 10 seconds (10000 milliseconds).

Step 02. Turn the Mode On and Off

Create a “On/ Off” switch to enable the Terminal to work automatically switch, when necessary, to Offline Mode.

  • To start the automatic checking:

  • TerminalHealth.startTerminalHealthCheck(terminal, callback);

  • TerminalHealth.startTerminalHealthCheck(terminal, callback);

  • [TerminalHealth startTerminalHealthCheck:terminal withListener:self];

  • TerminalHealth.StartTerminalHealthCheck(terminal, myListener);


The method above starts to check the connection Healthy of the informed Terminal (terminal argument) with its Payment Gateway, based on the timeout and interval configurations defined, and when the connection is not Healthy, changes the Terminal settings to work in Offline Mode.

Once the connection is Healthy again, the informed Terminal stops operating in Offline Mode automatically.

Once you set this mode, you can’t change the Terminal to or from offline mode manually like explained in the last section.

The change between operating online and offline is done automatically, once this method is executed.

About the arguments for this method:

  • terminal: a Terminal object representing the terminal you desire to automatically switch to Offline Mode, when necessary.
  • callback: a ITerminalHealthListener object, representing the callback to which the responses of these methods, which could be errors or a success, will be redirected to.

To change back and use the manual option, you need to first stop the automatic checking.


  • To stop the automatic switching:

  • TerminalHealth.startTerminalHealthCheck(terminal, callback);

  • TerminalHealth.startTerminalHealthCheck(terminal, callback);

  • [TerminalHealth stopTerminalHealthCheck:terminal withListener:self];

  • TerminalHealth.StopTerminalHealthCheck(terminal, myListener);


The method above stops the checking of the connection Healthy for the informed Terminal (terminal argument) with its Payment Gateway.

Once you stop the checking, you can use the manual setting to Offline Mode again.

About the arguments for this method:

  • terminal: a Terminal object representing the terminal you desire to stop the automatic switch to Offline Mode.
  • callback: a ITerminalHealthListener object, representing the callback to which the responses of these methods, which could be errors or a success, will be redirected to.


Additionally, for windows platform, you can setup a quantity of attempts (between 1 and 5) you prefer your application performing in checking the terminal's “Connection Health”, just by using the following configuration before starting the Terminal's Health Check.

  • TerminalHealth.SetAttempts(attemptsQuantity);


For more details, take a look at the SDK Documentation section and find more about the TerminalHealth class.

Treating the Sale Offline Request

Independently of working offline by choice or based on health verification, if you decide that you are going to work in Offline Mode, at some point, you need to treat the Offline Sale Requests (the result of submitting a sale when in offline mode) to be able to use the Offline Mode completely.

This result is received on a specific method (onOfflineSaleRequest), representing the data contained in the sale transaction that wasn’t submitted due to the Offline Mode, and as well as responses for other requests, needs to be implemented in the same class that implements the CoreApiListener interface.

  • public void onOfflineSaleRequest(CoreSale saleRequest){
     
        // here your application should implement a logic to save the request to a server, so later on, can be sent to the payment gateway
     
    }

  • public void onOfflineSaleRequest(CoreSale saleRequest){
     
        // here your application should implement a logic to save the request to a server, so later on, can be sent to the payment gateway
     
    }

  • - (void)onOfflineSaleRequest:(CoreSale)saleRequest{
     
        // here your application should implement a logic to save the request to a server, so later on, can be sent to the payment gateway

  • public void OnOfflineSaleRequest(CoreSale saleRequest){
     
        // here your application should implement a logic to save the request to a server, so later on, can be sent to the payment gateway
     
    }


Once the response is received, there’s still the issue about submitting it again to the Payment Gateway.

Sending the Offline Sales to the Gateway

After storing the Offline Sale Requests, at some point, they will need to be sent to the Payment Gateway.

To be able to do that, you need to implement a minimum logic, allowing to periodically (or based in some rule) trigger the submitting of those Offline Sale Requests.

Differently from a normal Sale, the submitting of a Offline Sale Request is going to be done not by a Terminal, but by a RestConnect, and there's no callback result, but a straight forward result with the Sale Response.

So send the Offline Sale Requests, all you need to do is to retrieve the transactions stored in Your Application that weren’t successfully sent yet, and send them to the Gateway, using the sendSale method available at the RestConnector class.


For more details, take a look at the SDK Documentation section and find more about the RestConnector class.