Getting Started with Java

The GoChip SDK is a library for communicating with the WorldNet Payment Gateway. It wraps a set of interfaces and logic that connects the Payment Gateway, the Card Reader Devices and the client's side security.

This page presents the basic steps to build your own solution using our SDK.


This guide is applicable from SDK Version 1.4.10 and For older versions, use the menu navigation on the left side of this page.

Step 01 - Download The Components

You can find our current supported version at the Download SDK Versions page.


Select the Plugins you'll be using in your application. That depends on the Card Reader Devices you are going to use. If you don't want to start from scratch, also download the Sample App provided to the version. This App will give you a good start point for you POS project.

Step 02 - Create Your Project and Install the SDK

The installation of the SDK is as easy as adding the GoChip SDK to your project. For that you need:

  • I) Copy the gochipsdk_version.jar to the application folder and add it as a dependency.
  • II) Copy payconfig.xml into your project.

The payconfig.xml file contains URLs used to access the servers, so don't forget to add it to your project, or the communication is not going to happpen.

If you want to start with the Sample App, just follow the steps of creating a new project from an existing source. Each IDE works in a different way, but when creating a new project, most offer an option to create based on an existing project or based on source files where you just have to point to a repository. This repository would be the decompressed folder of the Sample App in the last step of the previous section.


Please, note that the SDK requires a GSON dependency to be added to your project separately. If you are using gradlle, add the folloing line to the dependencies node:

dependencies {
    implementation ''

Step 03 - Implement the CoreAPIListener

The application needs to implement the Core API Listener (CoreAPIListener) to interact with the SDK.

On Java this makes the most sense in the MainController, as follows:

  • public class MainController implements CoreAPIListener{

For further reading on CoreAPIListener, consult the Core API Listener page at the SDK Documentation section.

The CoreAPIListener interface contains all the methods used for interactions.

If your application contains multiple views, instead of each view conforming CoreAPIListener interface and implementing all of its methods, you can use the following listeners, which are suited for your views.


Then, register the listeners implementing the interfaces above:

  • JavaTerminal.getInstance().registerCoreAPIDeviceListener(this);

Step 04 - Initialise the Terminal

  • I) You should use the Terminal (singleton instance) provided by the SDK.

Where this is an object that implements the CoreAPIListener (i.e. this code snippet is done inside the MainController)

  • JavaTerminal.getInstance().initialize(this);

The terminal can also be initialized without CoreAPIListener

  • JavaTerminal.getInstance().initialize();

  • II) Now, set the Terminal Mode, (TEST, DEV or LIVE), depending on your needs.

This is an easy one as well. All you have to do is to set the terminal mode to the right type.

The Test Mode should be used for development - It's going to make your app to use the gatewayTestUrl defined in payconfig.xml when communicating with the server. Before initiate your Terminal, enable the Test Mode:

  • JavaTerminal.getInstance().setMode(CoreMode.TEST);

After finishing the development of your app, don't forget to change the mode again to go Live (Live Mode, that points to gatewayLiveUrl defined in payconfig.xml file).

  • JavaTerminal.getInstance().setMode(CoreMode.LIVE);

You still have one option: the Dev Mode.

  • JavaTerminal.getInstance().setMode(CoreMode.DEV);

The Dev Mode is used to point to gatewayDevUrl defined in payconfig.xml file. The Dev Host usually contains unreleased features.

  • III) Now, set the Terminal Log Level (NONE, ERROR, TEST or FULL), depending on your needs.

This is also an easy one. All you have to do is to set the terminal log level to the right type.

  • LEVEL_FULL: This level will allow SDK to print all logs into the log file and the console. Level FULL will be default level for TEST or DEV mode.
  • LEVEL_TEST: This level will allow SDK to print logs which do no contain any sensitive data e.g. requests and responses to the server, tlv strings, emv tags, encrypted data, etc. Level Info will be default level for LIVE mode.
  • LEVEL_ERRORThis level will allow SDK to print only errors. Any error that occurs in the SDK, any error that the server returns, any error that the device returns. No other logs such as events, method calls will be printed.
  • LEVEL_NONE: This level will disable logs in the SDK.

  • JavaTerminal.getInstance().setLogLevel(LogLevel.LEVEL_FULL);

  • IV) Once the Terminal is created, initialize it.

The arguments are the terminal ID and secret. These are credentials required to use a Terminal using the SDK.

  • JavaTerminal.getInstance().initWithConfiguration(MainActivity.this, TERMINAL_ID, SECRET);

Step 05 - Handle the Initialisation Response

Once the Terminal is initialized, it is necessary to handle all response types.

The Terminal initialization attempts to connect to the server and the response must then be verified. The SDK does that with the methods: onError and onSettingsRetrieved.

Successful Response

If your initialization worked properly, without problems, your application is going to receive the response at the onSettingsRetrieved method.

  • @Override
    public void onSettingsRetrieved(CoreSettings settings) {
    	// ...

You need to use the argument returned to extract the response.

Unsuccessful Response

If anything went wrong with the initialization, your application is going to receive an error at the onError method.

  • @Override
    public void onError(CoreError error, String message) {
    	Log.d(TAG, "onError");
    	// ... treatment for initialization error

In the event of an error, your application can show the error text, a generic message or execute a particular action, based on the error.

Step 06 - Install Your Plugins


  • Java 1.8
  • Ubuntu 16.04 64bit


  • I) Copy the appropriate plugin(s) to your project folder.
  • II) Add the plugin libraries as dependencies for the project.

Installation for IDTECH devices

To connect to IDTECH device's native libraries, It will be necessary execute the following steps:

  • a) Extract libraries and symbolic links from IDTECH/ folder
  • b) Create file /etc/ - This file should contain the path to the extracted libs directory
  • c) From command line run sudo ldconfig
  • d) Additionally, if using a VP6300 device, please copy the NEO2_devices.xml from libs/IDTECH/ folder into your project.

Installation for INGENICO devices

To use this plugin install Ingenico's native libraries by executing the following steps:

  • a) Extract libraries from nativeLibsLinux/ 64 bit
  • b) Create file /etc/ - This file should contain the path to the extracted libs directory
  • c) From command line run sudo ldconfig

Alternatively, when using the InteliJ IDE, to find the native Ingenico libs, you must also set VM optionsto: -Djava.library.path=“path to native libs directory” which can be found in libs/ bit.

Permissions must be set for the USB device. This can be achieved by creating a new file in “/etc/udev/rules.d” named “usb.rules” - It must have the following contents:

SUBSYSTEM==“usb”, MODE=“0666”

Step 07 - Initialize the Device

Now we can initialize the device using our Terminal.

The first argument is a DeviceEnum corresponding to the device your application is going to use. The second argument is a connection type. The third argument is optional for iniatilizing a bluetooth device with a pre stored bluetooth address.

  • JavaTerminal.getInstance().initDevice(DeviceEnum.IDTECH, DeviceConnectionType.USB, null);

If the device is successfully connected, the onDeviceConnected callback will be triggered. If not, an Error is going to be generated and received in onError callback.

Step 08 - Implement Your Features

For further reading on how to execute transactions (Sale, Refund, Report, etc.) visit the section Default Mode and explore the options.

Also, in case you are interested in working with different flow configurations, like a offline terminal, visit Offline Mode, or with unattended terminals, visit Polling Mode. More options are also available in Transaction Flows.

The following pages will assist you in understanding and implementing your features:

If you have questions, please talk to us using the Contact link at the top (right side) of this page. We would love to help!