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

Requirements

The SDK targets .Net Framework 4.5.1.

Installation

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

Step 1 - Install .Net Framework 4.5.1

Step 2 - Extract GoChipSDK.zip.

Step 3 - Copy coresdk.dll, NewtonSoft.Jsoon.dll and HashLib.dll from library extracted folder to the application folder.

Step 4 - In solution explorer right click the project file and click Add reference. Find coresdk.dll, NewtonSoft.Jsoon.dll and HashLib.dll and click OK.

Step 5 - Add payconfig.xml into your project. Select payconfig.xml, in the file properties select under “Copy to Output Directory” to “Copy Always”. Select under Build Action to “Embedded Resource”.

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);

To establish SSL/TLS connection to the server please use the following code.

ServicePointManager.SecurityProtocol = SecurityProtocolType.Ssl3 | SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;

Core API Listener

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

public sealed partial class MainPage : Page, 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);
OnDeviceError(CoreDeviceError error, String message);
OnSettingsRetrieved(CoreSettings settings);
OnDeviceConnected(DeviceEnum type, Dictionary<String, String> deviceInfo);
OnDeviceDisconnected(DeviceEnum type);
OnSelectApplication(List<string> applications)
OnReversalRetrieved(CoreResponse response);
OnDeviceInfoReturned(Dictionary<String, String> deviceInfo);

OnMessage

Contains message coming from the SDK while processing the transaction.

public void OnMessage(CoreMessage message) {
   ...
}

OnSaleResponse

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

public void OnSaleResponse(CoreSaleResponse response) {
   string cardType = response.cardType;
   string name = response.cardHolderName;   
   ...
}

OnRefundResponse

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

public void OnRefundResponse(CoreRefundResponse response) {
   string cardType = response.cardType;
   string name = response.cardHolderName;   
 
   ...
 
}

OnTransactionListResponse

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

public void OnTransactionListResponse(CoreTransactions response) {
   List &ltCoreTransactionSummary> list = response.transactionSummary;
   foreach (CoreTransactionSummary tr in 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) {
      // Windows Desktop
      Process.Start(url);
}

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
 
 
}

OnError

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

public void OnError(CoreErrorType error) {
   ...
}

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) {
   List&ltCoreTax> tax = settings.taxList;
   List&ltCoreTip> tip = settings.tipList;
   ...
}

OnDeviceConnected

Fires when device gets connected.

public void OnDeviceConnected(DeviceEnum type, Dictionary
 
               deviceInfo){ ... }
 

OnDeviceDisconnected

Fires when device gets disconnected.

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

OnSelectApplication

Fires when application selection is required by plugin.

public void OnSelectApplication(List&ltstring> applications){
   terminal.SubmitApplication(0);
}

OnReversalRetrieved

Fires after reversal has been processed succesfully.

public void OnReversalRetrieved(CoreResponse response){
}

OnDeviceInfoReturned

Device info is returned here.

public void OnDeviceInfoReturned(Dictionary<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 Page)

Terminal terminal = new Terminal(this);

Step 2 - Once the Terminal 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(TERMINAL_ID, SECRET);

Plugin Installation

Step 1 - Extract downloaded plugin.

Steps for Ingenico devices

Step 1 - On 32 bit systems the environment variable “Path” should be set correctly to ensure all the RBA_SDK dlls in “Resources” folder can be found by the application. Copy the path to “Resources” folder(contains necessary DLLs) and add this path to your machine’s Environment System Variable “PATH”.

Step 2 - On 64 bit systems. RBASDK.DLL is a 32-bit library and it needs to be run in 32-bit compatibility mode on a 64-bit machine. To do this, copy all the dlls from “Resources” folder to “C:\Windows\SysWOW64” folder.

Step 3 - Microsoft runtime libraries(msvcp100.dll, msvcp110.dll, msvcr100.dll, msvcr110.dll) should also be installed in the system if not already installed. You can either install ‘Microsoft Visual C++ Redistributable Package (x86)’ or you can manually copy these DLLs in “C:\WIndows\SysWOW64” folder.

Step 4 - Copy ingenico.dll and RBA_SDK_cs.dll from the extracted folder to the application folder.

Step 5 - In solution explorer right click the project file and click Add reference. Find ingenico.dll and RBA_SDK_cs.dll and click OK.

Step 6 - Make sure the target is set to x86 architecture.

To initialise the device.

Dictionary&ltstring, string> data = new Dictionary&ltstring, string>();
data.Add("portName", "COM1");
terminal.InitDevice(DeviceEnum.INGENICO, DeviceConnectionType.USB, data);

“portName” is a serial port where the device is connected to.

Getting the list of port names.

string[] ports = System.IO.Ports.SerialPort.GetPortNames();

Steps for Idtech devices

Step 1 - Copy all dll files from the extracted folder to the application folder.

Step 2 - In solution explorer right click the project file and click Add reference. Find idtech.dll and IDTechSDK.dll and click OK.

Step 3 - In solution explorer right click the project file and click Add Existing item. Find all other dll files and click Add. Select each dll file under properties select under “Copy to Output Directory” to “Copy Always”.

To initialise the device.

terminal.InitDevice(DeviceEnum.IDTECH, DeviceConnectionType.USB, null);

Transactions

Step 1 - Create the CoreSale object

Create a CoreSale object with the amount.

CoreSale sale = new CoreSale(Math.Round(12.3, 2, MidpointRounding.ToEven));

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.

public void OnSaleResponse(CoreSaleResponse response)
    string cardType = response.cardType;
}

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

public void OnError(CoreError error){
    ...
}

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:

public void OnSignatureRequired(CoreSignature signature)
{
    canvas.signature = signature;
}
StartTouch(x,y)
MoveTouch(x,y)
UpTouch(x,y)
ClearSignature()
SubmitSignature()

StartTouch - Mouse was pressed.

MoveTouch - Mouse has moved.

UpTouch - Mouse was released.

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.

Windows Desktop

private void Form1_MouseDown(object sender, MouseEventArgs e)
{
    draw = true;
    prevX = e.X;
    prevY = e.Y;
    if (signature != null)
    {
        signature.StartTouch((float)prevX, (float)prevY);
    }
}
 
private void Form1_MouseUp(object sender, MouseEventArgs e)
{
    draw = false;
    if (signature != null)
    {
        signature.UpTouch();
    }
}
 
private void Form1_MouseMove(object sender, MouseEventArgs e)
{
    if (draw)
    {
        currentX = e.X;
        currentY = e.Y;
        using (Graphics graphics = Graphics.FromImage(bitmap))
        {
            graphics.DrawLine(
            new Pen(new SolidBrush(Color.Black), 1), prevX, prevY, currentX, currentY);
        }
        prevX = e.X;
        prevY = e.Y;
        if (signature != null)
        {
            signature.MoveTouch((float)prevX, (float)prevY);
        }
        panel1.Invalidate();
    }
}
private void panel1_Paint(object sender, PaintEventArgs e)
{
    if (bitmap == null)
    {
        bitmap = new Bitmap(panel1.Width, panel1.Height);
    }
    base.OnPaint(e);
    e.Graphics.DrawImage(bitmap, new Point(0, 0));
}

Create corresponding touch event methods and asign them to your panel. Use signature object to send the coordinates taken from the mouse event. Use the graphics object to draw.

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.

In order to create custom Scheme protocol on Windows we need to add it into the Windows Registry using following method.

Make sure requestedExecutionLevel is set to requireAdministrator in app manifest.

<requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
public static void RegisterURI(string uriScheme)
{
    RegisterUriScheme("PATH TO YOUR EXE FILE", "schemeName");
}
static void RegisterUriScheme(string appPath, string uriScheme)
{
    // HKEY_CLASSES_ROOT
    using (RegistryKey hkcrClass = Registry.ClassesRoot.CreateSubKey(uriScheme))
    {
        hkcrClass.SetValue(null, "URL:"+ uriScheme+ " Protocol");
        hkcrClass.SetValue("URL Protocol", String.Empty, RegistryValueKind.String);
 
        // use the application's icon as the URI scheme icon
        using (RegistryKey defaultIcon = hkcrClass.CreateSubKey("DefaultIcon"))
        {
            string iconValue = String.Format("\"{0}\",0", appPath);
            defaultIcon.SetValue(null, iconValue);
        }
 
        // open the application and pass the URI to the command-line
        using (RegistryKey shell = hkcrClass.CreateSubKey("shell"))
        {
            using (RegistryKey open = shell.CreateSubKey("open"))
            {
                using (RegistryKey command = open.CreateSubKey("command"))
                {
                    string cmdValue = String.Format("\"{0}\" \"%1\"", appPath);
                    command.SetValue(null, cmdValue);
                }
            }
        }
    }
}

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

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(string url)
{
    Process.Start(url);
}

Parse Token

In Windows Desktop. After successful login, the browser will redirects you back to the application with a token in the URI. You can get the token by Registering the Service class to handle URI from the browser. The best practice is to store the token in preferences as you don't need to login every time to make authenticated requests to a server.

Step 1- To prevent multiple instances of the same application we must register a service that opens an IpcServerChannel so that it can be consumed by other instances of the application.

Step 2- Connects to the service using an IpcClientChannel and returns a remote reference, or null if there is only one instance of the application.

Step 3- Handles the URI by performing the command.

Following is the example of URI handler.

public class URIHandler : MarshalByRefObject, URIHandlerInterface {
 
/// Registers the URI handler in the instance of the application.
public static bool Register() {
    try {
        IpcServerChannel channel = new IpcServerChannel("UriScheme");
        ChannelServices.RegisterChannel(channel, true);
        RemotingConfiguration.RegisterWellKnownServiceType(typeof(URIHandler), "URIHandler", WellKnownObjectMode.SingleCall);
 
        return true;
    }
    catch {
        Console.WriteLine("Error occurred.");
    }
 
    return false;
}
 
/// Returns the URI handler from the instance of the application, or null if there is no other instance.
public static URIHandlerInterface GetHandler() {
    try {
        IpcClientChannel channel = new IpcClientChannel();
        ChannelServices.RegisterChannel(channel, true);
        string address = String.Format("ipc://{0}/URIHandler", "UriScheme");
        URIHandlerInterface handler = (URIHandlerInterface)RemotingServices.Connect(typeof(URIHandlerInterface), address);
 
        // need to test whether connection was established
        TextWriter.Null.WriteLine(handler.ToString());
 
        return handler;
    }
    catch {
        Console.WriteLine("Error occurred.");
    }
    return null;
}
 
public bool HandleUri(Uri uri) {
    Program.MainForm.ParseUri(uri);
    return true;
}
}

Step 3- The application entry point Program.cs needs to be modified as follows.

internal static Form1 MainForm { get; private set; }
[STAThread]
static void Main(string[] args)
{
    System.Windows.Forms.Application.EnableVisualStyles();
    System.Windows.Forms.Application.SetCompatibleTextRenderingDefault(false);
 
    Uri uri = null;
    if (args.Length > 0)
    {
        // a URI was passed and needs to be handled
        try
        {
            uri = new Uri(args[0].Trim());
        }
        catch (UriFormatException)
        {
            Console.WriteLine("Invalid URI.");
        }
    }
 
    URIHandlerInterface handler = URIHandlerInterface.GetHandler();
    if (handler != null)
    {
        //  instance of the application is already running, handle the URI and get the token 
        if (uri != null) handler.HandleUri(uri);
    }
    else {
        // create new instance
        URIHandler.Register();
 
        MainForm = new Form1();
 
        if (uri != null)
        {
            // a URI was passed, parse the token
            MainForm.Shown += (o, e) => new URIHandler().HandleUri(uri);
        }
        System.Windows.Forms.Application.Run(MainForm);
    }
}

Step 4- Parse the token from URI.

 public void ParseUri(Uri uri)
{
    if (InvokeRequired)
    {
        BeginInvoke(new Action
 
       (ParseUri), uri); } else { Dictionary
 
         queryParameters = ParseQueryString(uri.ToString()); showToken(queryParameters); } } public void showToken(Dictionary
 
          queryParameters) { if (queryParameters.ContainsKey("authenticationToken")) { string token = queryParameters["authenticationToken"]; terminal.token = token; string date = queryParameters["validUntil"]; textOutput.Text = "Token " + token + "\n" + "Valid Until " + date + "\n"; } else { textOutput.Text = "Error occurred "; } } // Parse URI public Dictionary
 
           ParseQueryString(string uri) { string substring = uri.Substring(((uri.LastIndexOf('?') == -1) ? 0 : uri.LastIndexOf('?') + 1)); string[] pairs = substring.Split('&'); Dictionary
 
            output = new Dictionary
 
            (); foreach (string piece in pairs) { string[] pair = piece.Split('='); output.Add(pair[0], pair[1]); } return output; }
 
 
 
 
 
 

Tell terminal object about the token.

terminal.token = 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 refundRequest = new CoreUnreferencedRefund(Math.Round(12.3, 2, MidpointRounding.ToEven));
 refundRequest.cardHolderName = "Test User";
 refundRequest.cardNumber = "4111111111111111";
 refundRequest.cardCvv = "123";
 refundRequest.cardType = "VISA";
 refundRequest.expiryDate = "1218";
 refundRequest.reason = "reason";
 terminal.ProcessUnreferencedRefund(refundRequest);

Refund response will be returned in OnRefundResponse callback method.

List transactions With Filter

CoreTransactionFilter filter = new CoreTransactionFilter();
filter.resultsPerPage = 25;
filter.state = CoreTransactionState.ALL;
filter.startDate = "31-12-2015";
filter.endDate = "30-01-2016";
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/windows/1.3.2.txt · Last modified: 2017/06/08 09:59 (external edit)