EMV documentation for GoChip EMV. Easy integration to get you started.

What's new!

Version 1.3.2

  • Updated Nomad and Walker libraries to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Updated Nomad library to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Updated Nomad libraries to the latest version 3.1.0
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements
  • Added automatic or manual signature collection
  • Added error handling for submitSignature call
  • Various Bug fixes and improvements

Introduction

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

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

Requirements

Minimum Android version supported by the SDK is 4.4.

Installation

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.

Demo mode should be used for development, which will use demo Host defined in payconfig.xml. To enable demo mode.

terminal.setMode(CoreMode.DEMO);

To switch back to LIVE mode.

 terminal.setMode(CoreMode.LIVE);

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);
onDeviceConnectionError();
onSelectBTDevice(ArrayList<String>  devices);
onAutoConfigProgressUpdate(String progress);
onReversalRetrieved(CoreResponse reversalResponse);
onSelectSerialPort(ArrayList<String> ports);
onDeviceInfoReturned(HashMap<String, String> deviceInfo);

onMessage

Contains message coming from the SDK while processing the transaction.

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

onSaleResponse

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();  
   ...
}

onRefundResponse

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();  
 
   ...
 
}

onTransactionListResponse

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){       
 
   ...
 
   }
 
}

onLoginUrlRetrieved

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);
      i.setData(Uri.parse(url));
      startActivity(i);
}

onSignatureRequired

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
   signatureCanvas.setSignature(signature);
   signatureCanvas.submitSignature();
}

onError

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

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

onDeviceError

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

public void onDeviceError(CoreDeviceError error, String message){
   ...
}

onSettingsRetrieved

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();
   ...
}

onDeviceConnected

Fires when device gets connected.

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

onDeviceDisconnected

Fires when device gets disconnected.

public void onDeviceDisconnected(DeviceEnum type){
   ...
}

onSelectApplication

Fires when application selection is required by plugin.

public void onSelectApplication(ArrayList<String> applications){
   terminal.submitApplication(0);
}

onDeviceConnectionError

Fires when there is a problem connecting to the device.

public void onDeviceConnectionError(){
    ...
}

onSelectBTDevice

This method will return list of available devices.

public void onSelectBTDevice(ArrayList<String>  devices){
    ...
}

onAutoConfigProgressUpdate

Fires when there is a problem connecting to the device.

public void onAutoConfigProgressUpdate(String progress){
    ...
}

onReversalRetrieved

Fires after reversal has been processed succesfully.

public void onReversalRetrieved(CoreResponse reversalResponse){
    ...
}

onSelectSerialPort

Fires when the serial post needs to be selected.

public void onSelectSerialPort(ArrayList<String> ports){
    ...
}

onDeviceInfoReturned

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.

BBPosDevice

<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"/>

Rambler

<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.

@Override
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.

terminal.selectBTDevice(0);

Transactions

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.

terminal.processSale(sale);

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.

@Override
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.

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

Signature

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

  • All swiped transactions
  • Chip and signature transactions

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:

@Override
public void onSignatureRequired(final CoreSignature signature) {
   Log.d(TAG, "onSignatureRequired");
   signatureCanvas.setSignature(signature); // View object with signature member variable
}
startTouch(x,y)
moveTouch(x,y)
upTouch(x,y)
clearSignature()
submitSignature()

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.

@Override
public boolean onTouchEvent(MotionEvent event) {
   float x = event.getX();
   float y = event.getY();
 
   switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
         signature.startTouch(x, y);
         break;
      case MotionEvent.ACTION_MOVE:
         signature.moveTouch(x, y);
         break;
      case MotionEvent.ACTION_UP:
         signature.upTouch();
         break;
  }
 
  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.

terminal.submitSignature(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">
 
   ...
 
   <intent-filter>
      <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" />
   </intent-filter>
</activity>

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.

terminal.requestSecuredUrl("schemeName://com.scheme.example");

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.

@Override
public void onLoginUrlRetrieved(final String url) {
    Intent i = new Intent(Intent.ACTION_VIEW);
    i.setData(Uri.parse(url));
    startActivity(i);
}

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.

@Override
protected void onNewIntent(Intent intent) {
   super.onNewIntent(intent);
   setIntent(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
         terminal.setToken(token);
         getIntent().setDataAndType(null, null);
         String date = data.getQueryParameter("validUntilDate");  //contains date when token expires
      }
   }
}

Tell terminal object about the token.

terminal.setToken(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.

Refund

CoreUnreferencedRefund refund = new CoreUnreferencedRefund(BigDecimal.valueOf(12.3);
refund.setCardHolderName("Test user");
refund.setCardNumber("4111111111111111");
refund.setCardCvv("123");
refund.setCardType("VISA");
refund.setExpiryDate("1218");
refund.setReason("reason");
 
terminal.processUnreferencedRefund(refund);

Refund response will be returned in onRefundResponse callback method.

List transactions With Filter

CoreTransactionFilter filter = new CoreTransactionFilter();
filter.setItemsPerPage(25);
filter.setState(CoreTransactionState.ALL);
filter.setStartDate("31-12-2015:12:45:30:123");
filter.setEndDate("30-01-2016:12:45:30:123");
terminal.getTransactions(1, filter);

Without Filter

terminal.getTransactions();

The transactions will be returned in onTransactionListResponse callback method.

Copyright © 2017 PayConex Plus | Powered by DokuWiki
getting_started/android/1.3.2.txt · Last modified: 2017/09/21 10:35 (external edit)