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 GoChip SDK is an easy to use library that handles communication with the PayConex payment gateway. The SDK wraps a REST interface to the PayConex 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 payment gateway, which allows a very simple interface for doing transactions.

Download

Download the SDK

The SDK has 2 main components:

  • GoChip 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 GoChip SDK in your own app.

Download Sample App

Getting Started

Installation

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

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

Step 2 - Copy payconfig.xml into your project.

Sample App

IntelliJ IDE needs to be used to import and run the Sample app

To import the Sample app project using IntelliJ

Step 1 - Extract javaSample.zip

Step 2 - Open IntelliJ, select File, New, Project from existing sources

Step 3 - Navigate to project and click next

Step 4 - Tick import project from external module and select gradle from the list

Step 5 - Once, the project is imported, click on Run and Edit Configurations

Step 6 - From the side menu click on plus and select Application

Step 7 - Set main class to “com.payments.javaSample.MainForm” and Use classpath of module to “corepay-java_main”

Step 8 - Run the project

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 Main class)

JavaTerminal terminal = new JavaTerminal(this);

Step 2 - Once the JavaTerminal 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.

Initialise device

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

terminal.initDevice(DeviceEnum.Bluepad, DeviceConnectionType.BLUETOOTH, null);
terminal.initDevice(DeviceEnum.Bluepad, DeviceConnectionType.USB, null);

For devices connecting via bluetooth, device needs to be paired with a computer prior the connection. 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()

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 void mouseDragged(MouseEvent e) {
        points.add(e.getPoint());
        if (signature != null) {
            signature.moveTouch((float) e.getX(), (float) e.getY());
        }
        Graphics g = getGraphics();
        g.drawLine(xPressed, yPressed, e.getX(), e.getY());
 
        xPressed = getX();
        yPressed = e.getY();
        repaint();
    }
 
    @Override
    public void mousePressed(MouseEvent e) {
        points.add(e.getPoint());
        xPressed = xDragged;
        yPressed = yDragged;
        if (signature != null) {
            signature.startTouch((float) e.getX(), (float) e.getY());
        }
        repaint();
    }
 
    @Override
    public void mouseReleased(MouseEvent e) {
        Point emptyPoint = new Point();
        emptyPoint.setLocation(0, 0);
        points.add(emptyPoint);
        if (signature != null) {
            signature.upTouch();
        }
        repaint();
    }

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

Authentiation browser

Step 1- Create a new Java class called AuthenticationBrowser. This class will create a webview, open up an authentication URL and handles the login process.

class AuthenticationBrowser {
    private JFrame frame;
 
    AuthenticationBrowser(final String url) {
        frame = new JFrame("Browser");
        frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE);
        frame.getContentPane().setLayout(null); // do the layout manually
        final JFXPanel fxPanel = new JFXPanel();
        frame.add(fxPanel);
        frame.setVisible(true);
        fxPanel.setSize(new Dimension(600, 500));
        fxPanel.setLocation(new Point(0, 27));
        frame.getContentPane().setPreferredSize(new Dimension(600, 500));
        frame.pack();
        frame.setResizable(false);
 
        Platform.runLater(new Runnable() { // this will run initFX as JavaFX-Thread
            @Override
            public void run() {
                initFX(fxPanel, url);
            }
        });
    }
 
    /* Creates a WebView and fires up google.com */
    private void initFX(final JFXPanel fxPanel, String uri) {
        Group group = new Group();
        Scene scene = new Scene(group);
        fxPanel.setScene(scene);
 
        WebView webView = new WebView();
 
        group.getChildren().add(webView);
        webView.setMinSize(600, 500);
        webView.setMaxSize(600, 500);
 
        WebEngine webEngine = webView.getEngine();
        webEngine.load(uri);
    }
 
    void close() {
        frame.setVisible(false);
        frame = null;
    }
}

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

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) {
    SwingUtilities.invokeLater(new Runnable() {
            public void run() {
                browser = new AuthenticationBrowser(url);
            }
        });
}

Parse Token

You must call handleURL method when the app start to handle the protocol passed in requestSecuredUrl method. After successful login, the browser will redirects you back to the application with a token in the URI which contains URI with the token. The best practice is to store the token in preferences as you don't need to login every time to make authenticated requests to the server.

private void handleURL() {
URL.setURLStreamHandlerFactory(new URLStreamHandlerFactory() {
    public URLStreamHandler createURLStreamHandler(String protocol) {
        return "schemeName".equals(protocol) ? new URLStreamHandler() {
            protected URLConnection openConnection(URL url) throws IOException {
                return new URLConnection(url) {
                    public void connect() throws IOException {
                        browser.close();
                        System.out.println("Connected!");
                        Map<String, String> params = parseUrl(url);
                        String token = params.get("authenticationToken");
                        if (token != null) {
                            terminal.setToken(token);
                            textView.setText("Token is : " + token);
                        } else {
                            textView.setText("Invalid username or password");
                        }
                    }
                };
            }
        } : null;
    }
});
    }

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/java/1.3.2.txt · Last modified: 2017/06/08 09:59 (external edit)