What's new!

Version 1.4.3

  • Added support for integration token
  • Improved logging
  • Various Bug fixes and improvements
  • Updated Sample app to support Android studio version 3.0
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Added support for integration token
  • Improved logging
  • Various Bug fixes and improvements
  • Updated Sample app to support Android studio version 3.0
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Fixed issues with delayed auth on Ingenico devices
  • Initial release to support payconex gateway
  • Added support for Keyed transactions
  • Added support for Refunds
  • Added support for integration token
  • Improved logging
  • Various Bug fixes and improvements
  • Updated Sample app to support Android studio version 3.0
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Added support for integration token
  • Improved logging
  • Various Bug fixes and improvements
  • Updated Sample app to support Android studio version 3.0
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Fixed issues with delayed auth on Ingenico devices


The CoChip SDK is an easy to use library that handles communication with the PayConex Plus payment gateway. The SDK wraps a REST interface to the PayConex Plus gateway but also implements the client side security, making it even easier to connect.

Bellow are the plugins that has already been integrated into the PayConex Plus payment gateway, which allows a very simple interface for doing transactions.


Download the SDK

The SDK has 2 main components:

  • CoChip SDK

  • (Optional) Plugins

    If you are using one (or more) of the following devices you can add the corresponding plugin.

Download the Sample App

The Sample app shows how to implement CoChip SDK in your own app.

Download Sample App

Getting Started


Minimum Android version supported by the SDK is 4.4.


Installation is as easy as adding the CoChip SDK to your project. The steps for Android are as follows:

Step 1 - Copy the core-sdk.jar to the application folder and add it as a dependency.

Step 2 - Go to the AndroidManifest.xml and set these permissions.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Step 3 - Copy payconfig.xml into your project's res/values directory.

The payconfig.xml contains URL's used to access the server.

Please make sure to add the file into your project.

Test mode should be used for development, which will use gatewayTestUrl defined in payconfig.xml. To enable test mode.


To switch back to LIVE mode.


DEV mode is used to point to gatewayDevUrl defined in payconfig.xml file. Dev host usually contains unreleased features. To switch to DEV mode.


Core API Listener

The application needs to implement the Core API Listener to interact with the SDK. On Android this makes the most sense in the MainActivity as follows:

public class MainActivity implements CoreAPIListener{
List of CoreApiListener interface methods.
onMessage(CoreMessage message);
onSaleResponse(CoreSaleResponse response);
onRefundResponse(CoreRefundResponse response);
onTransactionListResponse(CoreTransactions response);
onLoginUrlRetrieved(String url);
onSignatureRequired(CoreSignature signature);
onError(CoreError error, String message);
onDeviceError(CoreDeviceError error, String message);
onSettingsRetrieved(CoreSettings settings);
onDeviceConnected(DeviceEnum type, HashMap<String, String> deviceInfo);
onDeviceDisconnected(DeviceEnum type);
onSelectApplication(ArrayList<String> applications);
onSelectBTDevice(ArrayList<String>  devices);
onAutoConfigProgressUpdate(String progress);
onReversalRetrieved(CoreResponse reversalResponse);
onSelectSerialPort(ArrayList<String> ports);
onDeviceInfoReturned(HashMap<String, String> deviceInfo);


Contains message coming from the SDK while processing the transaction.

public void onMessage(CoreMessage message) {
   String message = message.name(); 


Fires after transaction has been processed succesfully. Contains transaction response object from the server.

public void onSaleResponse(CoreSaleResponse response) {
   String cardType = response.getCardType();
   String name = response.getCardHolderName();  


Fires after refund has been processed succesfully. Contains refund response object from the server.

public void onRefundResponse(CoreRefundResponse response) {
   String cardType = response.getCardType();
   String name = response.getCardHolderName();  


Returns CoreTransactions object which consists of the list with the last 10 transactions in response to getTransactions method.

public void onTransactionListResponse(CoreTransactions response) {
   ArrayList &ltCoreTransactionSummary> list = response.getTransactionSummary();
   for(CoreTransactionSummary tr : list){       


Returns URL which needs to be used to sign in into SelfCare System in response to requestSecuredUrl method.

public void onLoginUrlRetrieved(String url) {
      // start browser to log in
      Intent i = new Intent(Intent.ACTION_VIEW);


Fires when signature is required for the transaction to be processed.

public void onSignatureRequired() {
   //create canvas to draw a signature and pass the signature object


This method is triggered after error has occured in the SDK.

public void onError(CoreErrorType error, String message) {
   String message = message;


This method is triggered when there is an error coming from the device.

public void onDeviceError(CoreDeviceError error, String message){


Sends back terminal settings object in response to init method.

public void onSettingsRetrieved(CoreSettings settings) {
   ArrayList<CoreTax> tax = settings.getTaxList();
   ArrayList<CoreTip> tip = settings.getTipList();


Fires when device gets connected.

public void onDeviceConnected(DeviceEnum type, HashMap
               deviceInfo){ String address = deviceInfo.get("bluetoothID"); String supportNFC = deviceInfo.get("isSupportedNfc"); ... }


Fires when device gets disconnected.

public void onDeviceDisconnected(DeviceEnum type){


Fires when application selection is required by plugin.

public void onSelectApplication(ArrayList<String> applications){


Fires when there is a problem connecting to the device.

public void onDeviceConnectionError(){


This method will return list of available devices.

public void onSelectBTDevice(ArrayList<String>  devices){


Fires when there is a problem connecting to the device.

public void onAutoConfigProgressUpdate(String progress){


Fires after reversal has been processed succesfully.

public void onReversalRetrieved(CoreResponse reversalResponse){


Fires when the serial post needs to be selected.

public void onSelectSerialPort(ArrayList<String> ports){


Device info is returned here.

public void onDeviceInfoReturned(HashMap<String, String> deviceInfo){

Core SDK Initialisation

Step 1 - An instance of a Terminal must be created first. Where this is an object that implements the Core API Listener (i.e. this code snippet is done inside the MainActivity)

AndroidTerminal terminal = new AndroidTerminal(this);

Step 2 - Once the AndroidTerminal is created, we need to initialise it.

The arguments are the terminal ID and secret. These are credentials that are required before using the SDK.

terminal.initWithConfiguration(MainActivity.this, TERMINAL_ID, SECRET);

Plugin Installation

Step 1 - Copy the plugin(s) to your project folder.

Step 2 - Add the libraries as dependencies.

Additional Device Permissions required

The following permissions need to be added to the AndroidManifest for each plugin.


<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>


<uses-permission android:name="android.permission.RECORD_AUDIO"/> 
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

Initialise device

Now we can initialise the plugin using our terminal object and the corresponding DeviceEnum value.

terminal.initDevice(DeviceEnum.BBPosDevice, DeviceConnectionType.BLUETOOTH, null);

For devices connecting via bluetooth, onSelectBTDevice method will return list of available devices. We need to choose the device from the list to be able to connect to it.

public void onSelectBTDevice(ArrayList<String> type) {

Make sure to call selectBTDevice (to connect to the device) passing the position of the device from the list.



Step 1 - Create the CoreSale object

Create a CoreSale object with the amount.

CoreSale sale = new CoreSale(BigDecimal.valueOf(Double.parseDouble(2.22)));

Make sure onSettingsRetrieved method has been called before processing any transaction.

Step 2 - Send the transaction online

Call the method processSale from the Terminal object, passing the sale object as the parameter.


Step 3 - Handle the response

Depending on the status of the transaction, the response from the SDK should appear in either:

Response Handling - If all goes well the sale response object is returned in the onSaleResponse sale argument.

For the transaction to be approved, response code which is returned in onSaleReponse must be set A.

Please make sure to check the response code which can be one of the following:

A - Approval (Transaction was approved)

D - Declined (Transaction was declined)

C - Pick Up (Type of decline which means that the card has been marked as lost or stolen by the cardholder)

R - Referral (Type of decline which means that the card has been marked as lost or stolen by the cardholder)

public void onSaleResponse(final CoreSaleResponse response) {
   String json = response.getAsJsonObject();
   Log.d(TAG, "onSaleResponse ");

Error Handling - Or else the onError callback is fired with an error message.

public void onError(CoreError coreError, String s) {
   Log.d(TAG, "onError");

To process keyed transactions

CoreSaleKeyed saleKeyed = new CoreSaleKeyed(BigDecimal.valueOf(12.3));
saleKeyed.setCardHolderName("Test user");


There are 2 types of transactions that require a signature to be sent with the request.

  • All swiped transactions
  • Chip and signature transactions

If the signature is collected on the paper receipt please set SignatureCollection field of the CoreSale object to “MANUAL”. This property will make sure that onSignatureRequired is not triggered.

To send a signature you need to collect the details and send them via the CoreSignature object.

Step 1 - Get an instance of CoreSignature.

The CoreSignature object is created for you and supplied via onSignatureRequired:

public void onSignatureRequired(final CoreSignature signature) {
   Log.d(TAG, "onSignatureRequired");
   signatureCanvas.setSignature(signature); // View object with signature member variable

StartTouch - User has reapplied their finger.

MoveTouch - User has moved their finger.

UpTouch - The user has lifted their finger.

ClearSignature - Clears the signature.

SubmitSignature - Submits the signature.

Step 2 - Populate the CoreSignature object.

Use a canvas to call the corresponding signature touch method on the user input.

public boolean onTouchEvent(MotionEvent event) {
   float x = event.getX();
   float y = event.getY();
   switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
         signature.startTouch(x, y);
      case MotionEvent.ACTION_MOVE:
         signature.moveTouch(x, y);
      case MotionEvent.ACTION_UP:
  return true;

Step 3 - Send the CoreSignature object.

When the signature is completed, submitSignature method should be called to let the SDK know that the user has completed the signature.


Authentication Token

Authentication token is used for every request that requires user authentication

  • Refunds
  • Reporting of Transactions
  • Updating Terminal Settings

Steps to retrieve authentication token from the server

Create Scheme

In order to request the URL, custom scheme needs to be defined in your app, for the browser (used for authentication) to send back the token to your application.

Step 1- Define your scheme in android manifest in your activity tag with single instance launch mode.

<activity  android:launchMode="singleInstance">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:host="com.scheme.example" android:scheme="schemeName" />

After this point you will be able to redirect to the app from the browser with the valid token after successful authentication.

Request URL

Once URL scheme has been defined, use terminal object to request a secured URL which takes your URL as a paramater.


Make sure the custom Scheme passed as a parameter match the one defined in your manifest.

Login in the Selfcare System

onLoginUrlRetrieved callback method will be triggered with the generated URL. This URL needs to be opened in the browser to login into the selfcare system.

public void onLoginUrlRetrieved(final String url) {
    Intent i = new Intent(Intent.ACTION_VIEW);

Parse Token

After successful login, the browser will redirects you back to the application with a token in the URI. You must override onNewIntent method which contains URI with the token. The best practice is to store the token in shared preferences as you don't need to login every time to make authenticated requests to the server.

protected void onNewIntent(Intent intent) {
   if (getIntent() != null) {
      Uri data = getIntent().getData();
      if (data != null && data.getQueryParameter("authenticationToken") != null) {
         String token = data.getQueryParameter("authenticationToken");
         storeToken(token); // save token in shared preferences
         getIntent().setDataAndType(null, null);
         String date = data.getQueryParameter("validUntilDate");  //contains date when token expires

Tell terminal object about the token.


Token is unique and valid for 48 hours as a default, after this time re-login will be required and the new token will be generated for this account.

Process authenticated requests

After this point you will be able to process refund, update terminal settings, list transactions.


CoreUnreferencedRefund refund = new CoreUnreferencedRefund(BigDecimal.valueOf(12.3);
refund.setCardHolderName("Test user");

Refund response will be returned in onRefundResponse callback method.

List transactions With Filter

CoreTransactionFilter filter = new CoreTransactionFilter();
terminal.getTransactions(1, filter);

Without Filter


The transactions will be returned in onTransactionListResponse callback method.