The new generation of Handpoint APIs and SDKs are engineered to make your life simpler, happier.

Awesomely simple

Created for humans, coders, geeks, no need of dark and complex knowledge of the payment industry.

Superly secure

We take care of the PCI side so you don't have to spend months becoming compliant.

The Handpoint card reader encrypts all sensitive cardholder data so your app does not have to deal with it.

Working with the SDK

The Handpoint Windows SDK is compatible with .NET Framework Version 4.

1. Download the SDK.

2. Create a new windows form project in Visual Studio 2010 (or above) using .Net Framework Version 4.0.

3a. Add the HandpointSDK NuGet Package

to your project.

3b. Alternatively you can manually download the .zip file and add "HandpointSDK.dll" library as reference to your project.

4. Follow the getting started guide, to get you up and running or dive into the documentation.

If you have any questions, do not hesitate to contact us.

How to implement a Sale Transaction

The below flow chart shows the interaction between the SDK, the payment terminal and your application. The orange arrows represent methods (requests) that need to be invoked to communicate with the Handpoint SDK's. The dark arrows represent events that need to be integrated in your code in order to retrieve information from the SDK´s and the card reader.

How to implement a Sale Transaction with Recovery feature

At some point, the connection between the SDK and the card reader can become unstable. For example, the Bluetooth connection can be cut in the middle of a sale transaction if the smartphone runs out of battery. If this happens, you need to have implemented the “transaction recovery feature” in order to get the receipts from the previous transaction and knowing if it was successful despite the connection problem.

Supported functionality

• Discovery of remote BT devices.
• Connect to remote BT device.
• Physical connection to HiPro external accessory.
• Automatic or manual reconnection to the card reader.
• Executing financial transaction.
• Reporting status of transactions.
• Control and access to device logs.
• Barcode scanner with HiPro card readers.
• Limited card reader simulation.

Processing Payments Simulation

Your test payments are sent against a test server on the Handpoint side which simulates the behavior of an acquiring bank. Funds are not moved and sensitive data from the card is fully encrypted. You can use trigger amounts to generate some specific responses from our server:

Getting started with the simulator

Introduction

Connecting to the simulator

The SDK offers a method in which you will need to specify the card reader to be used:

hapi.useDevice(new Device("Name", "Port", "Address", ConnectionMethod.****))
                

Simply set the ConnectionMethod to Simulator, i.e. ConnectionMethod.Simulator. The SDK does the rest. You don't need to search via bluetooth for surrounding card readers when using the simulator.

hapi.useDevice(new Device("Name", "Port", "Address", ConnectionMethod.Simulator))
            

Controlling responses

The simulator mimics the card reader as much as possible regarding information flow from the SDK interface to your application. It will return all the transaction statuses, transaction results and receipts.

Results of a transaction are controlled by the amount sent into the sale function:
The 3rd position from the right sets the desired financial status, 0 = Authorized and 1 = Declined.
The 4th position from the right sets the desired verification method, 0 = Signature and 1 = PIN.

hapi.Sale(X10XX, Currency.GBP); // amount = X 10 XX - where X represents an integer [0;9]

• X 00 XX = Signature authorized
• X 01 XX = Signature declined
• X 10 XX = Pin authorized
• X 11 XX = Pin declined

Let's start programming!

1. Create a C# class

Create a new C# class called MyClass and include com.handpoint.api as a dependency :

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using com.handpoint.api;
    
    namespace GettingStartedWithSimulator
    {
        class MyClass
        {
        }
    }
                    

2. Initialize the API

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using com.handpoint.api;
    
    namespace GettingStartedWithSimulator
    {
        class MyClass
        {
            Hapi api;
    
            public MyClass()
            {
                InitApi();
            }
            public void InitApi()
            {
                string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
                api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
                // The api is now initialized. Yay! we've even set a default shared secret!
                // The shared secret is a unique string shared between the card reader and your mobile application.
                // It prevents other people to connect to your card reader.
            }
        }
    }
                    

3. Implement the mandatory Events(Events.Required)

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using com.handpoint.api;
    
    namespace GettingStartedWithSimulator
    {
        class MyClass : Events.Required
        {
            Hapi api;
    
            public MyClass()
            {
                InitApi();
            }
    
            public void InitApi()
            {
                string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
                api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
                // The api is now initialized. Yay! we've even set a default shared secret!
                // The shared secret is a unique string shared between the card reader and your mobile application
                // It prevents other people to connect to your card reader
            }
    
            public void DeviceDiscoveryFinished(List<Device> devices)
            {
                // Only needed when using a payment terminal
                //here you get a list of Bluetooth payment terminals paired with your PC
                // You can also get a list of serial / USB payment terminals attached to your computer
    
            }
    
            public void SignatureRequired(SignatureRequest signatureRequest, Device device)
            {
                // You'll be notified here if a sale process needs a signature verification
                // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
                // This method will not be invoked if a transaction is made with a Chip & PIN card
    
                api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt
                // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
            }
    
            public void EndOfTransaction(TransactionResult transactionResult, Device device)
            {
                // The object TransactionResult holds the different receipts
                // Other information can be accessed through this object like the transaction ID, the amount...
            }
        }
    }
                    

4. Add a method to connect to the simulator

    public void Connect()
    {
        Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR);
        api.UseDevice(device);
    }
                    

5. Add a method to take payments with the simulator

The simulator mimics the card reader as much as possible regarding the information flow from the SDK interface to your application. The results of the transaction (declined, authorized) and the type of verification method (PIN, signature) will depend on the amount used.

You can get different responses from the simulator by setting different values for the amount parameter, e.g. for a Sale function :

    api.Sale(X10XX, Currency.GBP); // amount = X 10 XX - where X represents an integer [0;9]
                    

Amount Values

• X00XX = Signature authorized
• X01XX = Signature declined
• X10XX = PIN authorized
• X11XX = PIN declined

The 3rd number from right sets desired financial status, Authorized or Declined. Default status is Authorized.
The 4th number from right sets desired verification method, Signature or PIN. Default method is Signature.

Let´s add 4 methods to MyClass in order to represent the 4 cases above :

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using com.handpoint.api;
    
    namespace GettingStartedWithSimulator
    {
        class MyClass : Events.Required
        {
            Hapi api;
    
            public MyClass()
            {
                InitApi();
            }
    
            public void InitApi()
            {
                string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
                api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
                // The api is now initialized. Yay! we've even set a default shared secret!
                // The shared secret is a unique string shared between the card reader and your mobile application.
                // It prevents other people to connect to your card reader.
            }
    
            public void DeviceDiscoveryFinished(List <Device> devices)
            {
                 // Only needed when using a payment terminal
                 //Here you get a list of Bluetooth payment terminals paired with your PC
                 // You can also get a list of serial / USB payment terminals attached to your computer
    
            }
    
            public void Connect()
            {
                Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR);
                api.UseDevice(device);
            }
    
            public bool PayWithSignatureAuthorized()
            {
                return api.Sale(new BigInteger("10000"), Currency.GBP);
                // amount X00XX where X represents an integer [0;9] --> Signature authorized
            }
    
            public bool PayWithSignatureDeclined()
            {
                return api.Sale(new BigInteger("10100"), Currency.GBP);
                // amount X01XX where X represents an integer [0;9] --> Signature declined
            }
    
            public bool PayWithPinAuthorized()
            {
                return api.Sale(new BigInteger("11000"), Currency.GBP);
                // amount X10XX where X represents an integer [0;9] --> PIN authorized
            }
            public bool PayWithPinDeclined()
            {
                return api.Sale(new BigInteger("11100"), Currency.GBP);
                // amount X11XX where X represents an integer [0;9] --> PIN declined
            }
    
            public void SignatureRequired(SignatureRequest signatureRequest, Device device)
            {
                // You'll be notified here if a sale process needs a signature verification
                // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
                // This method will not be invoked if a transaction is made with a Chip & PIN card
    
                api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt.
                // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
            }
    
            public void EndOfTransaction(TransactionResult transactionResult, Device device)
            {
                // The object TransactionResult stores the different receipts
                // Other information can be accessed through this object like the transaction ID, the amount...
            }
        }
    }
                    

Let's create a User Interface!

1. Create buttons
• Go to your user interface (usually Form1.cs[Design])
• Select View > Toolbox
• In the toolbox, under “Common Controls” drag and drop 5 button items to the user interface
• Select "button1" > Right-Click > Properties
• Change the attribute "Name" from "button1" to "ConnectToSimulator"
• Change the attribute "text" from "button1" to "Connect To Simulator"
• Change the attribute "Name" from "button2" to "PayWithSignatureAuthorized"
• Change the attribute "text" from "button2" to "Pay With Signature Authorized"
• Change the attribute "Name" from "button3" to "PayWithSignatureDeclined"
• Change the attribute "text" from "button3" to "Pay With Signature Declined"
• Change the attribute "Name" from "button4" to "PayWithPinAuthorized"
• Change the attribute "text" from "button4" to "Pay With Pin Authorized"
• Change the attribute "Name" from "button5" to "PayWithPinDeclined"
• Change the attribute "text" from "button5" to "Pay With Pin Declined"


2. Create WebBrowsers

Now that we have our 5 buttons let´s create two webBrowsers items to display the merchant receipt as well as the cardholder´s receipt at the end of the transaction.

• Select View > Toolbox > Common Controls > WebBrowser
• Drag and drop two web browsers to the user interface
• Select View > Toolbox > Common Controls > Label
• Drag and drop two labels to the user interface in order to identify the webBrowser items
• Change the attribute "Name" from the left webBrowser to "MerchantReceiptBrowser"
• Change the attribute "Name" from the right webBrowser to "CardholderReceiptBrowser"
• Change the attribute "Name" from "label1" to "MerchantReceiptLabel"
• Change the attribute "text" from "label1" to "Merchant Receipt :"
• Change the attribute "Name" from "label2" to "CardholderReceiptLabel"
• Change the attribute "text" from "label2" to "Cardholder Receipt :"

Let's link our user interface with methods!

1. Referencing the user interface(Form1.cs) in MyClass

In MyClass.cs, create an instance of Form1 called UIClass and initialize it. Instantiate MyClass and add form1 as a parameter for the Class.

    class MyClass : Events.Required
        {
            Hapi api;
            private Form1 UIClass;
    
            public MyClass(Form1 form1)
            {
                InitApi();
                UIClass = form1;
            }
                    

2. Referencing Myclass in Form1.cs and link methods to the user interface

Go to Form1.cs[Design] and double click on the button "Connect To Simulator". By Double Clicking on the "Connect To Simulator" button you created a method called ConnectToSimulator_Click. Create a new instance of MyClass called "my" in Form1.cs then, inside the new method ConnectToSimulator_Click call the Connect() method from MyClass.

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Linq;
    using System.Text;
    using System.Windows.Forms;
    namespace GettingStartedWithSimulator
    {
        public partial class Form1 : Form
        {
            MyClass my;
    
            public Form1()
            {
                InitializeComponent();
                my = new MyClass(this);
            }
            private void ConnectToSimulator_Click(object sender, EventArgs e)
            {
                my.Connect();
            }
        }
    }
                    

Go back to Form1.cs[Design] and double click on each of the other buttons to automatically generate an OnClick method in Form1.cs. Link each of the buttons to the correct methods in MyClass.cs.

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Linq;
    using System.Text;
    using System.Windows.Forms;
    namespace GettingStartedWithSimulator
    {
        public partial class Form1 : Form
        {
            MyClass my;
            public Form1()
            {
                InitializeComponent();
                my = new MyClass(this);
            }
            private void ConnectToSimulator_Click(object sender, EventArgs e)
            {
                my.Connect();
            }
            private void PayWithSignatureAuthorized_Click(object sender, EventArgs e)
            {
                my.PayWithSignatureAuthorized();
            }
            private void PayWithSignatureDeclined_Click(object sender, EventArgs e)
            {
                my.PayWithSignatureDeclined();
            }
            private void PayWithPinAuthorized_Click(object sender, EventArgs e)
            {
                my.PayWithPinAuthorized();
            }
            private void PayWithPinDeclined_Click(object sender, EventArgs e)
            {
                my.PayWithPinDeclined();
            }
        }
    }
                    

Let´s display the receipts at the end of a transaction!

1. Fetch the cardholder's and merchant receipts from the method EndOfTransaction in MyClass

At this point all the buttons are connected but we are still missing to display the receipts in the webBrowsers. First, let´s get the receipts from the method EndOfTransaction in myClass.cs.

    public void EndOfTransaction(TransactionResult transactionResult, Device device)
            {
                UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt);
            }
                    

2. Create the DisplayReceipts method in form1.cs

    public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt);
            public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt)
            {
                //Only need to check for one of the webBrowsers
                if (MerchantReceiptBrowser.InvokeRequired)
                {
                    UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts);
                    this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt });
                }
                else
                {
                    MerchantReceiptBrowser.DocumentText = MerchantReceipt;
                    CardholderReceiptBrowser.DocumentText = CustomerReceipt;
                }
            }
                    

Final Result!

Here is how MyClass.cs and Form1.cs must eventually look like :

1. MyClass.cs :

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using com.handpoint.api;
    namespace GettingStartedWithSimulator
    {
        class MyClass : Events.Required
        {
            Hapi api;
            private Form1 UIClass;
            public MyClass(Form1 form1)
            {
                InitApi();
                UIClass = form1;
            }
    
            public void InitApi()
            {
                string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
                api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
                // The api is now initialized. Yay! we've even set a default shared secret!
                // The shared secret is a unique string shared between the card reader and your mobile application.
                // It prevents other people to connect to your card reader.
            }
    
            public void DeviceDiscoveryFinished(List<Device> devices)
            {
                // Only needed when using a payment terminal
                //Here you get a list of Bluetooth payment terminals paired with your PC
                // You can also get a list of serial / USB payment terminals attached to your computer
    
            }
    
            public void Connect()
            {
                Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR);
                api.UseDevice(device);
            }
    
            public bool PayWithSignatureAuthorized()
            {
                return api.Sale(new BigInteger("10000"), Currency.GBP);
                // amount X00XX where X represents an integer [0;9] --> Signature authorized
            }
    
            public bool PayWithSignatureDeclined()
            {
                return api.Sale(new BigInteger("10100"), Currency.GBP);
                // amount X01XX where X represents an integer [0;9] --> Signature declined
            }
    
            public bool PayWithPinAuthorized()
            {
                return api.Sale(new BigInteger("11000"), Currency.GBP);
                // amount X10XX where X represents an integer [0;9] --> PIN authorized
            }
            public bool PayWithPinDeclined()
            {
                return api.Sale(new BigInteger("11100"), Currency.GBP);
                // amount X11XX where X represents an integer [0;9] --> PIN declined
            }
    
            public void SignatureRequired(SignatureRequest signatureRequest, Device device)
            {
                // You'll be notified here if a sale process needs a signature verification
                // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
                // This method will not be invoked if a transaction is made with a Chip & PIN card
    
    
                api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt.
                // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
            }
    
            public void EndOfTransaction(TransactionResult transactionResult, Device device)
            {
                UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt);
            }
        }
    }
                    

2. Form1.cs :

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Linq;
    using System.Text;
    using System.Windows.Forms;
    namespace GettingStartedWithSimulator
    {
        public partial class Form1 : Form
        {
            MyClass my;
            public Form1()
            {
                InitializeComponent();
                my = new MyClass(this);
            }
            private void ConnectToSimulator_Click(object sender, EventArgs e)
            {
                my.Connect();
            }
            private void PayWithSignatureAuthorized_Click(object sender, EventArgs e)
            {
                my.PayWithSignatureAuthorized();
            }
            private void PayWithSignatureDeclined_Click(object sender, EventArgs e)
            {
                my.PayWithSignatureDeclined();
            }
            private void PayWithPinAuthorized_Click(object sender, EventArgs e)
            {
                my.PayWithPinAuthorized();
            }
            private void PayWithPinDeclined_Click(object sender, EventArgs e)
            {
                my.PayWithPinDeclined();
            }
    
            public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt);
            public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt)
            {
                //Only need to check for one of the webbrowsers
                if (MerchantReceiptBrowser.InvokeRequired)
                {
                    UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts);
                    this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt });
                }
                else
                {
                    MerchantReceiptBrowser.DocumentText = MerchantReceipt;
                    CardholderReceiptBrowser.DocumentText = CustomerReceipt;
                }
            }
        }
    }
                    

Let's run our program!

Run the program by clicking the "play" button, click on "Connect to simulator" and then Click on one of the payment types available and have a look at the receipts! Voila!

Getting started with a card reader

Introduction

Let's start programming!

1. Create a C# class

Create a new C# class called MyClass and include com.handpoint.api as a dependency :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;

namespace WindowsGettingStartedApp
{
class MyClass
{
}
}
            

2. Initialize the API

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;

namespace WindowsGettingStartedApp
{
class MyClass
{
    Hapi api;

    public MyClass()
    {
        InitApi();
    }

    public void InitApi()
    {
        string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
        // The api is now initialized. Yay! we've even set a default shared secret!
        // The shared secret is a unique string shared between the card reader and your mobile application.
        // It prevents other people to connect to your card reader.
        // You should replace this default shared secret by the one sent by our support team.
    }
}
}
            

3. Implement the mandatory Events(Events.Required)

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;

namespace WindowsGettingStartedApp
{
class MyClass : Events.Required
{
    Hapi api;
    Device device;

    public MyClass()
    {
        InitApi();
    }

    public void InitApi()
    {
        string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
        // The api is now initialized. Yay! we've even set a default shared secret!
        // The shared secret is a unique string shared between the card reader and your mobile application.
        // It prevents other people to connect to your card reader.
        // You should replace this default shared secret by the one sent by our support team.
    }

    public void DeviceDiscoveryFinished(List<Device> devices)
    {
      // here you get a list of Bluetooth payment terminals paired with your computer
      // You can also get a list of serial / USB payment terminals attached to your computer

    }

    public void SignatureRequired(SignatureRequest signatureRequest, Device device)
    {
        // You'll be notified here if a sale process needs a signature verification
        // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
        // This method will not be invoked if a transaction is made with a Chip & PIN card

        api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt.
        // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
    }

    public void EndOfTransaction(TransactionResult transactionResult, Device device)
    {
        // The object TransactionResult holds the different receipts
        // Other information can be accessed through this object like the transaction ID, the amount...
    }
}
}
            

4. Add a method to discover surrounding devices and connect to the card reader

Ensure that the card reader and PC are correctly paired via bluetooth.

public void DiscoverDevices()
{
api.ListDevices(ConnectionMethod.BLUETOOTH);
// This triggers the search for all the bluetooth devices around.
// You can also search for USB and Serial as a connection method
}

public void DeviceDiscoveryFinished(List<Device> devices)
{
foreach (Device device in devices)
{
    if (device.Name != null)
    {
        if (device.Name.Equals("PP0513901435"))
        // Put the name of your device, find it by doing C then up arrow on your card reader keypad
        {
            this.device = device;
            //We'll remember the device for this session, it is nice if you would do that too
            api.UseDevice(this.device);
            //Connection to the device is handled automatically in the API
        }
    }
}
}
            

5. Add a method to connect directly to the card reader

Instead of discovering the surrounding devices you can also directly connect to the card reader by implementing the following method:

public void DirectConnect()
{
    Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH);
    //new Device("name", "address", "port", ConnectionMethod);
    //The address always has to be written in UPPER CASE
    api.UseDevice(device);
}
            

6. Add a method to take payments

public bool Pay()
    {
        return api.Sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
    }
            

7. Add a method to disconnect from the card reader

public void Disconnect()
{
api.Disconnect();
}
            

8. Eventually, MyClass.cs must look like this after implementing all the necessary methods :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;

namespace WindowsGettingStartedApp
{
class MyClass : Events.Required
{
    Hapi api;
    Device device;

    public MyClass()
    {
        InitApi();
    }

    public void InitApi()
    {
        string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
        // The api is now initialized. Yay! we've even set a default shared secret!
        // The shared secret is a unique string shared between the card reader and your mobile application.
        // It prevents other people to connect to your card reader.
        // You should replace this default shared secret by the one sent by our support team.
    }

    public void DiscoverDevices()
    {
        api.ListDevices(ConnectionMethod.BLUETOOTH);
        // This triggers the search for all the bluetooth devices around.
        // You can also search for USB and Serial as a connection method
    }

    public void DeviceDiscoveryFinished(List<Device> devices)
    {
        foreach (Device device in devices)
        {
            if (device.Name != null)
            {
                if (device.Name.Equals("PP0513901435"))
                // Put the name of your device, find it by doing C then up arrow on your card reader keypad
                {
                    this.device = device;
                    //We'll remember the device for this session, it is nice if you would do that too
                    api.UseDevice(this.device);
                    //Connection to the device is handled automatically in the API
                }
            }
        }
    }

    // You can also connect directly to a specific device without having to discover the other devices around :
    public void DirectConnect()
    {
        Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH);
        //The MAC Adress always has to be written in UPPER CASE
        //new Device("name", "address", "port", ConnectionMethod);
        api.UseDevice(device);
    }

    public bool Pay()
    {
        return api.Sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
    }

    public void SignatureRequired(SignatureRequest signatureRequest, Device device)
    {
        // You'll be notified here if a sale process needs a signature verification
        // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
        // This method will not be invoked if a transaction is made with a Chip & PIN card

        api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt.
        // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
    }

    public void EndOfTransaction(TransactionResult transactionResult, Device device)
    {
        // The object TransactionResult holds the different receipts
        // Other information can be accessed through this object like the transaction ID, the amount...
    }

    public void Disconnect()
    {
        api.Disconnect();
    }
}
}
            

Let's create a User Interface!

1. Create buttons
• Go to your user interface (usually Form1.cs[Design])
• Select View > Toolbox
• In the toolbox, under “Common Controls” drag and drop 3 button items to the user interface
• Select "button1" > Right-Click > Properties
• Change the attribute "Name" from "button1" to "PayButton"
• Change the attribute "text" from "button1" to "Pay Now"
• Change the attribute "Name" from "button2" to "ConnectButton"
• Change the attribute "text" from "button2" to "Connect To Card reader"
• Change the attribute "Name" from "button3" to "DisconnectButton"
• Change the attribute "text" from "button3" to "Disconnect From Card Reader"


2. Create WebBrowsers

Now that we have our 3 buttons, let´s create two webBrowsers items to display the merchant receipt as well as the cardholder´s receipt at the end of the transaction.

• Select View > Toolbox > Common Controls > WebBrowser
• Drag and drop two web browsers to the user interface
• Select View > Toolbox > Common Controls > Label
• Drag and drop two labels to the user interface in order to identify the webBrowser items
• Change the attribute "Name" from the left webBrowser to "MerchantReceiptBrowser"
• Change the attribute "Name" from the right webBrowser to "CardholderReceiptBrowser"
• Change the attribute "Name" from "label1" to "MerchantReceiptLabel"
• Change the attribute "text" from "label1" to "Merchant Receipt :"
• Change the attribute "Name" from "label2" to "CardholderReceiptLabel"
• Change the attribute "text" from "label2" to "Cardholder Receipt :"

Let's link our user interface with methods!

1. Referencing the user interface(Form1.cs) in MyClass

In MyClass.cs, create an instance of Form1 called UIClass and initialize it. Instantiate MyClass and add form1 as a parameter for the Class.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;

namespace WindowsGettingStartedApp
{
class MyClass : Events.Required
{
    Hapi api;
    Device device;
    private Form1 UIClass;
    public MyClass(Form1 form1)
    {
        InitApi();
        UIClass = form1;
    }
            

2. Referencing Myclass in Form1.cs and link methods to the user interface

Go to Form1.cs[Design] and double click on the button "Pay Now". By Double Clicking on it you created a method called PayButton_Click. Create a new instance of MyClass called "my" in Form1.cs then, inside the new method PayButton_Click call the Pay() method from MyClass.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace WindowsGettingStartedApp
{
public partial class Form1 : Form
{
    MyClass my;
    public Form1()
    {
        InitializeComponent();
        my = new MyClass(this);
    }
    private void PayButton_Click(object sender, EventArgs e)
    {
        my.Pay();
    }
}
}
            

Go back to Form1.cs[Design] and double click on each of the other buttons to automatically generate an OnClick method in Form1.cs. Link each of the buttons to the correct methods in MyClass.cs.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace WindowsGettingStartedApp
{
public partial class Form1 : Form
{
    MyClass my;
    public Form1()
    {
        InitializeComponent();
        my = new MyClass(this);
    }
    private void PayButton_Click(object sender, EventArgs e)
    {
        my.Pay();
    }
    private void ConnectButton_Click(object sender, EventArgs e)
    {
        my.DiscoverDevices();
        //my.DirectConnect();
    }
    private void DisconnectButton_Click(object sender, EventArgs e)
    {
        my.Disconnect();
    }
}
}
            

Let´s display the receipts at the end of a transaction!

1. Fetch the cardholder's and merchant receipts from the method EndOfTransaction in MyClass

At this point all the buttons are connected but we are still missing to display the receipts in the webBrowsers. First, let´s get the receipts from the method EndOfTransaction in myClass.cs.

public void EndOfTransaction(TransactionResult transactionResult, Device device)
    {
        UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt);
    }
            

2. Create the DisplayReceipts method in form1.cs

public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt);
public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt)
{
//Only need to check for one of the webbrowsers
if (MerchantReceiptBrowser.InvokeRequired)
{
    UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts);
    this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt });
}
else
{
    MerchantReceiptBrowser.DocumentText = MerchantReceipt;
    CardholderReceiptBrowser.DocumentText = CustomerReceipt;
}
}
            

Final Result!

Here is how MyClass.cs and Form1.cs must eventually look like :

1. MyClass.cs :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using com.handpoint.api;
namespace WindowsGettingStartedApp
{
class MyClass : Events.Required
{
    Hapi api;
    Device device;
    private Form1 UIClass;
    public MyClass(Form1 form1)
    {
        InitApi();
        UIClass = form1;
    }
    public void InitApi()
    {
        string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        api = HapiFactory.GetAsyncInterface(this).DefaultSharedSecret(sharedSecret);
        // The api is now initialized. Yay! we've even set a default shared secret!
        // The shared secret is a unique string shared between the card reader and your mobile application.
        // It prevents other people to connect to your card reader.
        // You should replace this default shared secret by the one sent by our support team.
    }
    public void DiscoverDevices()
    {
        api.ListDevices(ConnectionMethod.BLUETOOTH);
        // This triggers the search for all the bluetooth devices around.
        // You can also search for USB and Serial as a connection method
    }
    public void DeviceDiscoveryFinished(List<Device> devices)
    {
        foreach (Device device in devices)
        {
            if (device.Name != null)
            {
                if (device.Name.Equals("PP0513901435"))
                // Put the name of your device, find it by doing C then up arrow on your card reader keypad
                {
                    this.device = device;
                    //We'll remember the device for this session, it is nice if you would do that too
                    api.UseDevice(this.device);
                    //Connection to the device is handled automatically in the API
                }
            }
        }
    }
    // You can also connect directly to a specific device without having to discover the other devices around :
    public void DirectConnect()
    {
        Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH);
        //The MAC Adress always has to be written in UPPER CASE
        //new Device("name", "address", "port", ConnectionMethod);
        api.UseDevice(device);
    }
    public bool Pay()
    {
        return api.Sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
    }
    public void SignatureRequired(SignatureRequest signatureRequest, Device device)
    {
        // You'll be notified here if a sale process needs a signature verification
        // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
        // This method will not be invoked if a transaction is made with a Chip & PIN card
        api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt.
        // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it
    }
    public void EndOfTransaction(TransactionResult transactionResult, Device device)
    {
        UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt);
    }
    public void Disconnect()
    {
        api.Disconnect();
    }
}
}
            

2. Form1.cs :

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
namespace WindowsGettingStartedApp
{
public partial class Form1 : Form
{
    MyClass my;
    public Form1()
    {
        InitializeComponent();
        my = new MyClass(this);
    }
    private void PayButton_Click(object sender, EventArgs e)
    {
        my.Pay();
    }
    private void ConnectButton_Click(object sender, EventArgs e)
    {
        my.DiscoverDevices();
        //my.DirectConnect();
    }
    private void DisconnectButton_Click(object sender, EventArgs e)
    {
        my.Disconnect();
    }
    public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt);
    public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt)
    {
        //Only need to check for one of the webbrowsers
        if (MerchantReceiptBrowser.InvokeRequired)
        {
            UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts);
            this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt });
        }
        else
        {
            MerchantReceiptBrowser.DocumentText = MerchantReceipt;
            CardholderReceiptBrowser.DocumentText = CustomerReceipt;
        }
    }
}
}
            

Let's run our program!

Run the program by clicking the "play" button :

1. Click on "Connect To Card Reader", this can take a little bit of time (10 sec max) due to the fact that we are looking for all the devices around before connecting to a specific one
2. Click "Pay Now"
3. Follow the instructions on the card reader
4. When the transaction is finished, the receipts should be displayed in the webBrowsers
5. Click on "Disconnect From Card Reader" to stop the connection with the card reader