You are currently viewing the documentation for version

Introduction

The Handpoint Express SDK is composed of a Custom URL Protocol, a javascript interface and the Handpoint Express application running on the clients platform. The Handpoint Express application acts as a bridge between the web browser and the bluetooth card reader. When a transaction is initiated from the web based point of sale it reaches outside of the browser via a custom url. The Express application then takes care of finalizing the transaction with the card reader and sends the result and receipts back to the web application at the end of the operation.

Handpoint Express Installation

Windows

The Windows Express app is portable since version 1.3.2!
This means that you don't need to install it, just download it and run it once. We take care of the rest.
It will download updates automatically so you don't have to worry about that.
However if you had a previous version installed it is advised that you uninstall it previously to avoid confusion and conflicts.

Android & iOS

Download the Android & iOS Express apps directly from the Android Play Store or iOS App Store.

Downloads

Get the Express apps!

Get the SDK!

Javascript Express SDK

Data Flow

Setup

Download and install the app for your platform and start integrating, either directly through the custom url scheme or by using our Javascript interface that abstracts the messaging format. You can start developing as soon as you receive a Handpoint payment terminal. Your end user, the merchant, only has to install the Express application on the platform of her choice to start accepting card present payments seamlessly with your application and a Handpoint card reader.

Sandbox

We've built a tool to help you in your development and testing of this solution. Check it at: https://handpoint.com/express

You can generate sample transactions, test the experience in your browser and see the responses if you enable the sandbox mode.

When sandbox mode is enabled you are provided with a uniqe URL which you can use for callbacks when testing your own application.


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:
Sale amounts
Amount Behaviour
37.79 Issuer response code = 01 (Refer to issuer)
37.84 Issuer response code = 05 (Not authorized)
37.93 Issuer response code = 04 (Pick up card)
37.57 Request is partially approved
37.68 Request timeout

Custom URL

To initiate an Express client transaction from your web or app, you open a URL with the following format: handpoint://express/v1/?data=<url_encoded_data>

  • For web apps, you can open this URL just as you would any other URL on a webpage.
  • For native iOS apps, you use the openURL: method of UIApplication.

The query parameter in the URL, data, is a percent-encoded JSON object that contains the information Express client needs to process the transaction request.

For example, a valid unencoded JSON object looks like this (replace CLIENT_ID with your application's ID, and SHARED_SECRET_KEY with the device activation key you receive from our support team): If you're opening this URL from a native app, you can use your own app's custom scheme as a callback: "myapp-url-scheme://payment-complete"

{
    "action": {
        "type": "sale",
        "parameters": {
            "amount": 1500,
            "currency": "USD"
        },
        "extraParameters": {
            "your custom field" : "custom value"
        }
    },
    "client": {
        "clientId": "CLIENT_ID",
        "ssk": "SHARED_SECRET_KEY",
        "autoReturn": true,
        "autoReturnTimeout": 0
    },
    "callbackUrl": "http://yourbackend.com/payment-result"
}

If you're developing a web application, this Javascript sample demonstrates encoding a Register API URL and directing the merchant's browser to open it:

<script>
var dataParameter = {
    "action": {
        "type": "sale",
        "parameters": {
            "amount": 1500,
            "currency": "USD"
        },
        "extraParameters": {
            "your custom field" : "custom value"
        }
    },
    "client": {
        "clientId": "CLIENT_ID",
        "ssk": "SHARED_SECRET_KEY",
        "autoReturn": true,
        "autoReturnTimeout": 0
    },
    "callbackUrl": "http://yourbackend.com/payment-result"
};
window.location = "handpoint://express/v1/?data=" + encodeURIComponent(JSON.stringify(dataParameter));
</script>

Json Request

Request fields

Name Type Description
action object Required. Contains the transaction type and relevant parameters
client object Required. Contains information specific to the client setup

Action fields

Name Type Description
type string Required. The type of transaction you intend to perform, currently supported types are "sale", "refund", "saleReversal", "refundReversal", "saleAndTokenizeCard", "enableScanner"
parameters object Required. An object containing the keys an values with the parameters required for this transaction.
extraParameters object Required. Contains a custom set of keys and values passed that will go to the gateway and will be delivered back in the response. Useful for tracking the transactions, merchants, etc...

Transaction Parameters fields

Name Type Description
amount string Required. The amount of money, in the smallest unit of the applicable currency. For US dollars, this value is in cents. (So, $12 would result in 1200. $0.01 would result in 1) This value is always an integer.
currency string Required. The type of currency involved in the current payment, in ISO 4217 format. For example, the currency code for US dollars is USD.
originalTransactionID string Required. (Required for reversals.) The original transaction Id required to reverse/cancel a transaction.

Barcode / QR Scanner Parameters fields

Name Type Description
multiScan boolean Optional. True if you want the scanner to stay on to capture multiple codes. False to shut off after the first succesful scan, timeout or cancel. Default is False
autoScan boolean Optional. True if you want the scanner to function automatically without the press of a button. Default is False.
resultsGrouped boolean Optional. True if you want the results of the scan to come all grouped when the scanner is turned off. Otherwise the device will send an event per each code scanned. Default is True.
timeout integer Optional. The amount of seconds after which the scanner, if left idle, turns itself off. Default is 0.

Client fields

Name Type Description
clientId string Arbitrary identification of the client. Your APP_ID or just an unique identifier of your web client.
ssk string Shared Secret Key to activate the card reader.
autoReturn boolean Required. If true, Express client automatically gets hidden/switches back to your app following a short timeout after the transaction completes. Otherwise, the merchant must tap the Back button to return to your app.
autoReturnTimeout integer Number of seconds to wait before switching back to your app if autoReturn is true. The default value is 10

Json Response

The response object is sent to the callback url and contains data relevant to the financial operation. It contains relevant information, extra parameters, a representation of the TransactionResult object returned from our native libraries and any error that occurred.

It is formatted in JSON and structured as a collection of "name":"value" pairs. Values are always a string except in the cases where the value is a boolean or another collection of "name":"value" pairs.

The response will be packed and added to your callbackUrl in the following format https://your_callback_url?data=<packed_response_data> in a GET request.

<packed_response_data> is a JSON string that has been URL encoded to make it safe to use as a GET parameter.


Response sample

        
        { "metadata": {
            "appVersion": "1.0.0",
            "systemInfo": {
                "osName": "Windows 7 Home edition",
                "deviceName": "PP917838383832",
                "internetConnectionType": [
                    "WiFi",
                    "Ethernet"
                ]
            },
            "protocolVersion": "v1"
        },
        "transactionResult": {
            "statusMessage": "AUTH CODE 12345",
            "type": "SALE",
            "finStatus": "AUTHORISED",
            "requestedAmount": "1000",
            "gratuityAmount": "000",
            "gratuityPercentage": "0",
            "totalAmount": "1000",
            "currency": "USD",
            "transactionID": "00021010001-10033331231",
            "eftTransactionID": "778799887-77798987-798798878887888",
            "originalEftTransactionID": "778799887-77798987-798798878887888",
            "eftTimestamp": "1476113261",
            "authorisationCode": "155884656588899",
            "verificationMethod": "PIN",
            "cardEntryType": "ICC",
            "cardSchemeName": "VISA",
            "errorMessage": "No error",
            "customerReference": "0000000",
            "budgetNumber": "0",
            "recoveredTransaction": false,
            "cardTypeId": "U015",
            "merchantReceipt": "https://url_to_merchant_receipt",
            "customerReceipt": "https://url_to_customer_receipt"
        },
        "deviceStatus": {
            "serialNumber": "615856933558",
            "batteryStatus": "100%",
            "batterymV": "234",
            "batteryCharging": "Charging",
            "externalPower": "Connected",
            "applicationName": "EFTClient",
            "applicationVersion": "2.15.789"
        },
        "extraParameters" : {}
    }

Metadata fields

Name Type Description
appVersion string A string representation of the client version.
systemInfo object An object containing info about the Express client
protocolVersion string A string representation of the Express protocol version used in this request.

SystemInfo fields

Name Type Description
osName string A string containing the name and version of the OS the client is running in.
deviceName string A string containing the Bluetooth name of the card reader.
internetConnectionType array A list of the available internet connection methods.

Javascript Interface

We provide a simple Javascript interface for web based implementations. It is a helper library that generates URLs for the different types of transactions.

To use it you must include hapiexpress.js in your code and initialise it before generating the urls.


Example for a 10$ sale

        
    let ssk = '0102030405060708091011121314151617181920212223242526272829303132';
    let shouldAutoReturn = false;
    let autoReturnTimeout = 0;

    initHapiExpress('hapi-tests', ssk, shouldAutoReturn, autoReturnTimeout);

    let amount = 1000; // Translates to 10.00
    let currency = "USD"
    let callbackurl = "http://example.com/callbackID"
    let url = Hapi.urlForSale(amount, currency, {'extra-value':'some info'}, callbackurl);
    Hapi.openUrl(url);

Javascript Methods

initHapiExpress

method Available since 1.0

initHapiExpress

Creates an instance of Hapi.

Parameters

Parameter Notes
client_id *
string		 A unique identifier of your system to group operations
ssk *
string		 The shared secret key to authorize the operations
auto_return *
Boolean		 If true, Handpoint Express automatically switches back to your app following a short timeout after the transaction completes.


Returns

object
The Hapi interface object with functions to generate URLs for sale, refund and reversals

Code example

initHapiExpress('hapi-tests', '010203040050606', false);

openUrl

method Available since 1.1

openUrl

Opens a URL that is passed. This is a helper method. URLs generated by the UrlFor... methods can also be opened just like a normal link.

Parameters

Parameter Notes
url *
string		 Url to open


Code example

Hapi.openURL('handpoint://express/v1/?data=')

urlForRefund

method Available since 1.0

urlForRefund

Constructs the URL needed for opening the express app and starting a refund operation.

Parameters

Parameter Notes
amount *
integer		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
string		 Currency of the charge
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForRefund('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');

urlForRefundReversal

method Available since 1.0

urlForSale

Constructs the URL needed for opening the express app and reverting a refund transaction. This operation tries to void an earlier refund transaction, therefor the transaction GUID is needed for the transaction to be voided.

Parameters

Parameter Notes
amount *
integer		 Amount of funds in the original transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
string		 Currency of the charge
originalTransactionID *
string		 The transaction id number for the transactino to void/revert
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForRefundReversal('1000', 'USD', '1234' {'extra-value':'some info'}, 'http://callback.com');

urlForSale

method Available since 1.0

urlForSale

Constructs the URL needed for opening the express app and starting a sale.

Parameters

Parameter Notes
amount *
integer		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
string		 Currency of the charge
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForSale('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');

urlForSaleAndTokenizeCard

method Available since 1.2

urlForSaleAndTokenizeCard

Constructs the URL needed for opening the express app and starting a saleAndTokenizeCard.

Parameters

Parameter Notes
amount *
integer		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
string		 Currency of the charge
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForSaleAndTokenizeCard('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');

urlForSaleReversal

method Available since 1.0

urlForSaleReversal

Constructs the URL needed for opening the express app and reverting a sale transaction. This operation tries to void an earlier sale transaction, therefor the transaction GUID is needed for the transaction to be voided.

Parameters

Parameter Notes
amount *
integer		 Amount of funds in the original transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
string		 Currency of the charge
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
originalTransactionID *
string		 The transaction id number for the transactino to void/revert
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForSaleReversal('1000', 'USD', '1234' {'extra-value':'some info'}, 'http://callback.com');

urlForScanner

method Available since 1.2

urlForScanner

Constructs the URL needed for opening the express app and starting scanning.

Parameters

Parameter Notes
multiScan
boolean		 True if you want the scanner to stay on to capture multiple codes. False to shut off after the first succesful scan, timeout or cancel. Default is False
autoScan
boolean		 True if you want the scanner to function automatically without the press of a button. Default is False.
resultsGrouped
boolean		 True if you want the results of the scan to come all grouped when the scanner is turned off. Otherwise the device will send an event per each code scanned. Default is True.
timeout
integer		 The amount of seconds after which the scanner, if left idle, turns itself off. Default is 0.
extra_parameters
object		 An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url *
string		 callback_url The URL that Handpoint Express will send its response to.


Returns

string
A complete constructed and encoded URL string that includes the data for opening the express app and performing the operation

Code example

Hapi.urlForScanner(false, false, true, 0, {'extra-value':'some info'}, 'http://callback.com');