Handpoint documentation

Introduction

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.; Integration in less than two days, or we don't get cookies for christmas.

Superly Robust: We take care of the PCI side so you don't have to.; The Handpoint card reader encrypts all sensitive cardholder data so your app will not need to handle any sensitive data.

Brand new!: The Handpoint SDK has been rebuilt from scratch. Using C# as our codebase and simplicity of integration as our goal.

Working with the SDK: The Handpoint Windows SDK is compatible with .NET Framework Version 4.; 1. Download the SDK and usb driver for the card reader which are provided in the zip file.; 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; 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.; On dev.handpoint.com you can find a quick start guide for Visual Studio as well as getting started guides with a development kit or the simulator!; If you have any questions, do not hesitate to contact us.

Simulator

To start building your application and test simple changes without having to use a card reader you can use the built in simulator.

Using the simulator

If you follow the Getting started guide for the hapi SDK there is a method used there which tells the SDK which device to use,

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 for devices 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 hapi interface to your application. E.g. it will return all the transaction statuses, transaction results and receipts. Results are controlled by the 3rd and 4th numbers from the right in the amount parameter.

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.

Values

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

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

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

Replacing the 'X's with numbers then the example will result in a successful transaction where the verification method of the transaction was done through a correct PIN input.

Transactions

Sale

method Available since 1.0.0

Sale

A sale initiates a payment operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters.

Parameters

Parameter	Type	Validation	Notes
`amount`	BigInteger	Required	Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`currency`	Currency	Required	Currency of the charge
`map`	Map	Optional	A map including extra optional transaction parameters.

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired: Invoked if card verification requires signature.
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Initiate a sale for 10.00 Pounds
api.Sale(new BigInteger(1000),Currency.GBP);

Reversal

method Available since 1.0.0

SaleReversal

A sale Reversal, also called sale VOID allows the user to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. In it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter	Type	Validation	Notes
`amount`	BigInteger	Required	Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`currency`	Currency	Required	Currency of the charge
`originalTransactionID`	String	Required	As received from the card reader (EFTTransactionID)
`map`	Map	Optional	A map including extra optional transaction parameters.

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired: Invoked if card verification requires signature.
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Initiate a reversal for 10.00 Pounds
api.SaleReversal(new BigInteger(1000),Currency.GBP,"1234567");

Refund

method Available since 1.0.0

Refund

A refund initiates a refund operation to the card reader. This operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters.

Parameters

Parameter	Type	Validation	Notes
`amount`	BigInteger	Required	Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`currency`	Currency	Required	Currency of the charge
`map`	Map	Optional	A map including extra optional transaction parameters.

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired: Invoked if card verification requires signature.
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Initiate a refund for 10.00 in Great British Pounds
api.Refund(new BigInteger(1000),Currency.GBP);

Refund reversal

method Available since 1.0.0

RefundReversal

A Refund Reversal, also called Refund VOID allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. In it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter	Type	Validation	Notes
`amount`	BigInteger	Required	Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
`currency`	Currency	Required	Currency of the charge
`originalTransactionID`	String	Required	As received from the card reader (EFTTransactionID)
`map`	Map	Optional	A map including extra optional transaction parameters.

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired: Invoked if card verification requires signature.
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Initiate a refund reversal for 10.00 in Great British Pounds
api.RefundReversal(new BigInteger(1000),Currency.GBP,"1234567");

Signature result

method Available since 1.0.0

SignatureResult

A signatureRequest event is invoked during transaction when signature verification is needed (f.ex when payment is done with a magstripe card). The merchant is required to ask the cardholder for signature and approve (or disapprove) the signature. signatureResult tells the card reader if the signature was approved by passing true in the method. To disapprove then false is passed.

Parameters

Parameter	Type	Validation	Notes
`accepted`	Boolean	Required	pass true if merchant accepts customer signature

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Receiving a SignatureRequest from the SDK.
public void SignatureRequired(SignatureRequest signatureRequest, Device device)
{
    //If you accept the signature
    api.SignatureResult(true);
}

Cancel transaction

method Available since 1.0.0

CancelRequest

This method attempts to cancel the current transaction on the card reader. Note that operations cannot be cancelled at certain points during the transaction process

Events invoked

currentTransactionStatus: Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
endOfTransaction: Invoked when the card reader finishes processing the transaction

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Attempts to cancel an operation
api.CancelRequest();

Device management

Connect

method Available since 1.0.0

UseDevice

Configures the device as the preferred device and tries to connect to it. Everytime a new connection is started the SDK will make 3 attempts to reestablish the connection. If those attempts fail, the connection is considered dead.

Parameters

Parameter	Type	Validation	Notes
`device`	Device	Required	This parameter specifies to the system which device you want to use for the operations.

Events invoked

ConnectionStatusChanged: Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information.

Returns

Boolean: true if the operation was successful.

Code example

//Connect to a device
Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH);

api.UseDevice(device);

Disconnect

method Available since 1.0.0

Disconnect

Disconnects from default device.

Events invoked

ConnectionStatusChanged: Causes the connection manager to invoke this event with the appropriate information.

Returns

Boolean: true if the operation was successful.

Code example

//Disconnect from current device
api.Disconnect();

Set shared secret

method Available since 1.0.0

SetSharedSecret

Validates the app for this session, thus enabling financial transactions

Parameters

Parameter	Type	Validation	Notes
`sharedSecret`	String	Required	The shared secret is a key provided by Handpoint when you get your account that enables you to perform live operations with the card reader. However, if you're developing with a starter kit, the test shared secret is specified in the example

Events invoked

None: No events invoked.

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Sets the shared secret using the test key
api.SetSharedSecret("0102030405060708091011121314151617181920212223242526272829303132");

Set parameter

method Available since 1.0.0

SetParameter

Changes values of certain parameters on the card reader.

Parameters

Parameter	Type	Validation	Notes
`param`	DeviceParameter	Required	The name of the parameter to change
`value`	String	Required	New value of the parameter

Events invoked

None: No events are invoked.

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Changes the bluetooth name of card reader
api.SetParameter(DeviceParameter.BluetoothName, "OrangeCardReader");

Set logging level

method Available since 1.1.2

SetLogLevel

Sets the log level of the hapi for both the device and the API.

Parameters

Parameter	Type	Validation	Notes
`level`	LogLevel	Required	The desired log level. Can be LogLevel.None, LogLevel.Info, LogLevel.Full, LogLevel.Debug

Events invoked

None: No events are invoked.

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Sets the log level to info
api.SetLogLevel(LogLevel.info);

Request device logs

method Available since 1.0.0

GetDeviceLogs

Fetches the logs from the device and reports them to the DeviceLogsReady event.

Events invoked

deviceLogsReady: Invoked when hapi has finished downloading logs from the card reader.

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Downloads logs from device
api.GetDeviceLogs();

Update device

method Available since 1.0.0

Update

The update operation checks for update to the card reader and initiates an update if needed.

Events invoked

None: Information about this process should be available at the device's screen.

Returns

Boolean: true if the operation was successfully sent to device

Code example

//Check for card reader update
api.Update();

List Devices (search)

method Available since 1.0.0

ListDevices

Starts the search for devices to connect with the specified ConnectionMethod

Parameters

Parameter	Type	Validation	Notes
`method`	ConnectionMethod	Required	The means of connection you intend to use to talk to the device. (Bluetooth, Serial, USB, etc...)

Events invoked

deviceDiscoveryFinished: Invoked after the search is finished returning a list of the devices finished.

Code example

//Search for Bluetooth devices
api.ListDevices(ConnectionMethod.BLUETOOTH);

Events subscribers

Add Required Event Handler

method Available since 1.0.0

AddRequiredEventHandler

Adds a listener so necessary information can be retrieved. Such as signature verification, receipts and list of devices. This listener fetches information from the following events : DeviceDiscoveryFinished, SignatureRequired and EndOfTransaction. The corresponding removal method, RemoveRequiredEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter	Type	Validation	Notes
`listener`	Required	Required	An implementation of the Events.Required interface

Returns

Boolean: true if the new listener was added successfully

Code example

//Register a listener for required events
this.api.AddRequiredEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Required {

    void SignatureRequired(SignatureRequest request, Device device);

    void EndOfTransaction(TransactionResult result, Device device);

    void DeviceDiscoveryFinished(List devices);
}

Add Status Notification Event Handler

method Available since 1.0.0

AddStatusNotificationEventHandler

Adds a listener so transaction information can be retrieved. This listener fetches information from the following events : ConnectionStatusChanged, CurrentTransactionStatus. The corresponding removal method, RemoveStatusNotificationEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter	Type	Validation	Notes
`listener`	Status	Required	An implementation of the Events.Status interface

Returns

Boolean: true if the new listener was added successfully

Code example

//Register a listener for transaction information events
this.api.AddStatusNotificationEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Status {

    void ConnectionStatusChanged(ConnectionStatus status, Device device);

    void CurrentTransactionStatus(StatusInfo info, Device device);
}

Add Log Event Handler

method Available since 1.0.0

AddLogEventHandler

Adds a listener so log information can be retrieved. This listener fetches information from the following events : OnMessageLogged, DeviceLogsReady. The corresponding removal method, RemoveLogEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter	Type	Validation	Notes
`listener`	Log	Required	An implementation of the Events.Log interface

Returns

Boolean: true if the new listener was added successfully

Code example

//Register a listener for log information events
this.api.AddLogEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Log {

    void DeviceLogsReady(String logs, Device device);

    void OnMessageLogged(LogLevel level, String message);
}

Remove Required Event Handler

method Available since 1.0.0

RemoveRequiredEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter	Type	Validation	Notes
`listener`	Required	Required	The listener to be removed

Returns

Boolean: true if the listener was removed successfully

Code example

//Remove a listener for required events
this.api.RemoveRequiredEventHandler(this);

Remove Status Notification Event Handler

method Available since 1.0.0

RemoveStatusNotificationEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter	Type	Validation	Notes
`listener`	Status	Required	The listener to be removed

Returns

Boolean: true if the listener was removed successfully

Code example

//Remove a listener for status notification events
this.api.RemoveStatusNotificationEventHandler(this);

Remove Log Event Handler

method Available since 1.0.0

RemoveLogEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter	Type	Validation	Notes
`listener`	Log	Required	The listener to be removed

Returns

Boolean: true if the listener was removed successfully

Code example

//Remove a listener for log events
this.api.RemoveLogEventHandler(this);

Events

Device discovery finished

method Available since 1.0.0

DeviceDiscoveryFinished

deviceDiscoveryFinished event gets called when a device discovery has finished and returns a list of devices.

Parameters

Parameter	Type	Validation	Notes
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddRequiredEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve the devices information.

Code example

//Receiving a list of connectable devices
List<Device> myListOfDevices = new List<Device>();
public void DeviceDiscoveryFinished(List<Device> devices)
{
    foreach(Device device in devices)
    {
        myListOfDevices.Add(device);
    }
}

Signature required

method Available since 1.0.0

SignatureRequired

signatureRequired event gets called when a card requires a signature instead of PIN entry and has two parameters, request and device.

Parameters

Parameter	Type	Validation	Notes
`request`	SignatureRequest	Required	Holds the signature request
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddRequiredEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve signature information.

Code example

//Receiving a SignatureRequest from the SDK.
public void SignatureRequired(SignatureRequest signatureRequest, Device device)
{
    //You might want to print out the receipt or ask the customer to sign the receipt on your device
    DisplayReceiptInUI(signatureRequest.MerchantReceipt)
    //If you accept the signature
    api.SignatureResult(true);
}

End of transaction

method Available since 1.0.0

EndOfTransaction

EndOfTransaction event gets called at the end of each transaction and has two parameters, result and device.

Parameters

Parameter	Type	Validation	Notes
`result`	TransactionResult	Required	Holds the results for the transaction
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddRequiredEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve transaction information.

Code example

//Receiving a TransactionResult from the SDK.
public void EndOfTransaction(TransactionResult transactionResult, Device device)
{
    //You might want to display this information in the UI
    postTransactionResultToUI(transactionResult);
}

Connection status changed

method Available since 1.0.0

ConnectionStatusChanged

ConnectionStatusChanged event gets called when the state of a card reader connection changes.

Parameters

Parameter	Type	Validation	Notes
`status`	ConnectionStatus	Required	An enum containing the status code for the connection
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddStatusNotificationEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve the different connection statuses (e.g : CONNECTED, DISCONNECTED...).

Code example

//Receiving a new ConnectionStatus from the SDK
public void ConnectionStatusChanged(ConnectionStatus connectionStatus, Device device)
{
    //You might want to display this information in the UI
    postNewStatusToUI(connectionStatus);
}

Current transaction status

method Available since 1.0.0

CurrentTransactionStatus

currentTransactionStatus event gets called when the state of an ongoing transaction changes.

Parameters

Parameter	Type	Validation	Notes
`statusInfo`	StatusInfo	Required	An object containing information about the current transaction
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddStatusNotificationEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve the different states from the card reader (e.g : Waiting for card, Waiting for PIN entry...).

Code example

//Receiving a transaction status from the SDK.
public void currentTransactionStatus(StatusInfo statusInfo, Device device)
{
    //You might want to display some of this information in the UI
    DisplayTransactionStatusInUI(statusInfo)
}

Message logged

method Available since 1.0.0

OnMessageLogged

OnMessageLogged event gets called for all log messages that are being logged. This is only intended for debugging.

Parameters

Parameter	Type	Validation	Notes
`logLevel`	LogLevel	Required	An enum containing the log level
`message`	String	Required	A String containing the current log message

Subscribers Needed

AddLogEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve the different log messages.

Code example

//Receiving a log from the SDK
public void OnMessageLogged(LogLevel logLevel, String message)
{
    //You do not want to display this information in the UI
    Debug.WriteLine(message);
}

Logs ready

method Available since 1.0.0

DeviceLogsReady

DeviceLogsReady event gets called when the card reader logs requested by a call to getDeviceLogs() are ready. This Event is really useful if there has been a communication error between the card reader and the API (e.g : Bluetooth communication lost). After reconnecting, you can then fetch the card reader logs to the API.

Parameters

Parameter	Type	Validation	Notes
`logs`	String	Required	String containing the current log
`device`	Device	Required	The device that is invoking the event

Subscribers Needed

AddLogEventHandler: This listener has to be implemented (preferably during initialisation) in order to retrieve the card reader logs.

Code example

//Receiving a log from the device
public void DeviceLogsReady(string logs, Device device)
{
    //You might want to save this information
    WriteLogsToDisk(logs);
}

Objects

Transaction Type

enum Available since 1.0.0

TransactionType

An enum representing different types of transactions.

Possible values

UNDEFINED SALE VOID_SALE REFUND VOID_REFUND CANCEL_SALE CANCEL_REFUND

Transaction Result

object Available since 1.1.3

TransactionResult

A class holding information about a transaction result.

Properties

Property	Type	Accessor	Description
`StatusMessage`	String	get	Gets the status message from the `TransactionResult`. The status message is a human readable string from our servers which contains a value representing the result from the server side. "AUTH CODE 12345" for an example.
`Type`	TransactionType	get	Gets the transaction type from the `TransactionResult`. The transaction type represents which type of transaction was done. "SALE" for an example.
`FinStatus`	FinancialStatus	get	Gets the financial status from the `TransactionResult`. The financial status describes the conclusion of the transaction as received from the card reader. "AUTHORISED" for an example.
`RequestedAmount`	BigInteger	get	Gets the requested amount from the `TransactionResult`. The requested amount is the payment amount sent in the original request to the card reader, i.e. the amount which was to charge the card with.
`GratuityAmount`	BigInteger	get	Gets the gratuity amount from the `TransactionResult`. The gratuity amount is an additional amount added to the requested payment amount which represents additional fee added to the requested amount. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. The customer inputs an additional amount as a tip, lets say 100. The card is then charged for the requested amount, 1000, as well as the additional gratuity amount, 100. The result will be that the card will be charged for 1100. A calculated gratuity percentage will also be returned.
`GratuityPercentage`	double	get	Gets the gratuity percentage from the `TransactionResult` The gratuity percentage is used to calculate an additional amount to the requested amount. The card reader calculates that amount, rounded up to the closest whole number. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. Instead of the customer adding a value he selects the percentage of the requested amount to be applied as a tip, lets say 10%. The card is then charged for the requested amount, 1000, as well as the additional gratuity percentage, 10%. The result will be that the card will be charged for 1100. A calculated gratuity amount will also be returned.
`TotalAmount`	BigInteger	get	Gets the total amount from the `TransactionResult`. The total amount is the amount the card was charged for. It is possible that the total amount is not the same as the requested amount since an additional fee can be added, with the customer's approval, via the tipping functionality.
`Currency`	Currency	get	Gets the currency from the `TransactionResult`. The currency used in this transaction.
`TransactionID`	String	get	Gets the device transaction id from the `TransactionResult`. The transaction id is an internal increasing counter in the card reader which is incremented in each transaction.
`eFTTransactionID`	String	get	Gets the device transaction id from the `TransactionResult`. The EFT (electronic funds transfer) transaction id is a unique GUID from the servers which is linked to this transaction in order to search for a particual transaction. This id is used if a transaction is to be reversed.
`OriginalEFTTransactionID`	String	get	Gets the original EFT transaction id from the `TransactionResult`. The original EFT (electronic funds transfer) transaction id is a unique GUID previously received from the servers in order to reverse a transaction. This id is sent with the new eFTTransactionID in order to reference the original transaction. An example: A transaction is made. An eFTTransactionID is received. That transaction has to be reversed. A new transaction is started, now a reverse transaction, with the previously received eFTTransactionID as a parameter in the transaction. In the end result there will be a new eFTTransactionID, for the reverse transaction, and an originalEFTTransactionID referencing the original transaction.
`eFTTimestamp`	Date	get	Gets the time stamp from the `TransactionResult`. The eFTTimestamp represents the time when the transaction was done. This time is set by the device communicating to the card reader when the connection is established to the card reader.
`AuthorisationCode`	String	get	Gets the authorisation code from the `TransactionResult`. If the transaction was authorised the value represented can be used to search for a transaction in our system.
`VerificationMethod`	VerificationMethod	get	Gets the verification method from the `TransactionResult`. The verification method represents the card holder verification method used to allow the payment. "PIN" for an example.
`CardEntryType`	CardEntryType	get	Gets the card entry type from the `TransactionResult`. The card entry type is the method the card information was input to card reader. "ICC" for an example represents "Integrated Circuit Card" i.e. the information was read from the chip of the card.
`CardSchemeName`	String	get	Gets the card scheme name from the `TransactionResult`. The scheme which was used when the transaction was made.
`ErrorMessage`	String	get	Gets the error message from the `TransactionResult`. If there was an error during the transaction it is represented here in a human readable text.
`CustomerReference`	String	get	Gets the customer reference from the `TransactionResult`. If a customer reference was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The customer reference can be used to reference in internal systems.
`BudgetNumber`	String	get	Gets the budget number from the `TransactionResult`. If a budget number was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The budget number can be used to split payments over a period of months.
`MerchantReceipt`	String	get	Gets the merchant receipt from the `TransactionResult`. An HTML containing the merchant receipt.
`CustomerReceipt`	String	get	Gets the customer receipt from the `TransactionResult`. An HTML containing the customer receipt.
`DeviceStatus`	DeviceStatus	get	Gets the device status from the `TransactionResult`.

Handpoint API (Hapi) factory

object Available since 1.0.0

HapiFactory

A factory to provide a unified entrypoint and to simplify the way to instantiate the Hapi object.

Methods

Static factory

getAsyncInterface( Events.Required requiredListener );

Parameter	Type	Validation	Notes
`requiredListener`	Events.Required	Required	A listener object to report the required events.

Code example

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!
}

Connection Method

enum Available since 1.1.2

ConnectionMethod

An enum representing different types of connection methods.

BLUETOOTH, USB, SERIAL and SIMULATOR are supported for Windows.

Possible values

USB SERIAL BLUETOOTH HTTPS WIFI ETHERNET SIMULATOR

Code example

//Currently BLUETOOTH, USB, SERIAL and SIMULATOR are the only ConnectionMethod available.
public enum ConnectionMethod 
{
	USB,
	SERIAL,
	BLUETOOTH,
	HTTPS,
	WIFI,
	ETHERNET
	SIMULATOR
}

Device

object Available since 1.0.0

Device

An object to store the information about the device we're working with.

Methods

Constructor

Device( String name , String address , String port , ConnectionMethod connectionMethod , String sharedSecret , int timeout );

Parameter	Type	Validation	Notes
`name`	String	Required	A name to identify the device
`address`	String	Required	The address of the device you wish to connect to. E.g.: "08:00:69:02:01:FC" for bluetooth or "192.168.1.105" for ethernet.
`port`	String	Required	The port to connect to.
`connectionMethod`	ConnectionMethod	Required	Enumerated type to specify the type of connection with the device. E.g: Bluetooth, Serial, etc...
`sharedSecret`	String	Optional	This is used if you want this specific device to use the specified sharedSecret instead of the default one proviced in the initialization.
`timeout`	int	Optional	The amount of miliseconds to consider the connection has timed out. If not set, the default timeout is 15 seconds.

Properties

Property	Type	Accessor	Description
`Id`	String	get	An unique identifier of the device.

Code example

//Create and init a new Device
Device dev = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH);

Connection Status

enum Available since 1.1.2

ConnectionStatus

A list of statuses given to a connection

Possible values

Connected Connecting Disconnected Disconnecting Initializing NotConfigured

Signature Request

object Available since 1.1.2

SignatureRequest

A class containing information about a signature request/signature verification.

Properties

Property	Type	Accessor	Description
`Timeout`	int	get	`int` the value of the timeout in seconds.
`MerchantReceipt`	String	get	`String` the merchant receipt as html.

Currency

enum Available since 1.0.0

Currency

An enum of most currencies in the world.

Contains the ISO name, ISO number and the name of the currency. Additionally contains information about how many decimals the currency uses.

Possible values

AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYR BZD CAD CDF CHF CLP CNY COP COU CRC CUC CUP CVE CZK DJF DKK DOP DZD EEK EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LTL LVL LYD MAD MDL MKD MMK MNT MOP MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD STD SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UZS VEF VND VUV WST XAF XCD XOF XPF YER ZAR ZMK ZWL

Device Parameter

enum Available since 1.0.0

DeviceParameter

An enum describing all the available commands to send to a device.

When used a legal value is expected with the command

Possible values

BluetoothName BluetoothPass SystemTimeout ScreenTimeout SignatureTimeout

Device Status

object Available since 1.1.2

DeviceStatus

A class that holds the device status.

Properties

Property	Type	Accessor	Description
`SerialNumber`	String	get	Gets the serial number of the device
`BatteryStatus`	String	get	Gets the battery status in percentages of a device
`BatterymV`	String	get	Gets the battery milli volts of a device
`BatteryCharging`	String	get	Gets the battery charging status of a device
`ExternalPower`	String	get	Gets the status of an external power of a device
`ApplicationName`	String	get	Gets the application name used on a device
`ApplicationVersion`	String	get	Gets the application version number used on a device

Financial Status

enum Available since 1.0.0

FinancialStatus

An enum representing different statuses of a finalized transaction

Possible values

UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED

Status Info

object Available since 1.0.0

statusInfo

A class containing information about the status of the transaction.

Properties

Property	Type	Accessor	Description
`CancelAllowed`	bool	get	A `bool` representing if the card reader will accept a cancel request.
`status`	Status	get	A `Status` enum representing the status of the transaction.
`message`	string	get	A `String` containing the status message of the transaction.
`DeviceStatus`	DeviceStatus	get	A `DeviceStatus` object containing information about the device.

Log Level

enum Available since 1.0.0

LogLevel

An enum describing the different levels of logging used in the hapi and used in the device.

Possible values

None Info Full Debug

Optional Transaction Parameters

object Available since 1.0.0

OptionalParameters

A class containing optional transaction parameters now supported by the device.

Properties

Property	Type	Accessor	Description
`Budget`	String	static	Budget is only available for sale transactions. A `String` representing the key for a budget number. A budget number can be used to split up an amout over a period of months. The value has to be a `String` of 2 digits representing the number of months to split the transaction to. Example: "03" or "24"
`CustomerReference`	String	static	CustomerReference is available for all transactions. A `String` representing the key for a customer reference. A customer reference can be used for an internal marking system. The value is sent as a `String` of a maximum 25 characters and received back when the transaction has been processed. Example: "C.nr. 212311"

Verification Method

enum Available since 1.0.0

VerificationMethod

An enum representing different verification methods used in the transaction.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED

Status

enum Available since 1.0.0

status

An enum containing information about the status of the transaction.

Possible values

UserCancelled WaitingForCard CardInserted ApplicationSelection ApplicationConfirmation AmountValidation PinInput ManualCardInput WaitingForCardRemoval TipInput AuthenticatingPos WaitingForSignature ConnectingToHost SendingToHost ReceivingFromHost DisconnectingFromHost PinInputComplete Undefined

Card Entry Type

enum Available since 1.0.0

CardEntryType

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP