Introduction

Handpoint Browser SDK is composed of a Custom URL Protocol, javascript interface and an express application that runs on the clients platform and acts as a bridge between the web browser and the card reader. When a transaction is initiated from the browser based POS it reaches outside of the browser via a custom url. The Express app then takes care of finalising the transaction with a Handpoint card reader and sends the results and user back to the pos application at the end of the operation.

version 1.2.0.3




version 1.0.0



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 by using the bundled card reader simulator so you don't have to wait for a Handpoint development device. 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.


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
    },
    "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
    },
    "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"
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...

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.

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.

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 compressed with the GZDeflate algorithm, Base 64 encoded and 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": "<html>Sample receipt</html>",
            "customerReceipt": "<html>Sample receipt<</html>"
        },
        "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

        
    var ssk = '0102030405060708091011121314151617181920212223242526272829303132';
    initHapiExpress('hapi-tests', ssk, false);

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

Javascript Methods

urlForSale

method Available since 1.0.0

urlForSale

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

Parameters

Parameter Type Validation Notes
amount integer Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency string Required Currency of the charge
extra_parameters object Optional An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url string Required 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');

urlForSaleReversal

method Available since 1.0.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 Type Validation Notes
amount integer Required Amount of funds in the original transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency string Required Currency of the charge
extra_parameters object Optional An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
originalTransactionID string Required The transaction id number for the transactino to void/revert
callback_url string Required 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');

urlForRefundReversal

method Available since 1.0.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 Type Validation Notes
amount integer Required Amount of funds in the original transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency string Required Currency of the charge
originalTransactionID string Required The transaction id number for the transactino to void/revert
extra_parameters object Optional An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url string Required 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');

urlForRefund

method Available since 1.0.0

urlForRefund

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

Parameters

Parameter Type Validation Notes
amount integer Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency string Required Currency of the charge
extra_parameters object Optional An object containing additional sale parameters, fx. Key: "Budget", Value: "03"
callback_url string Required 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');

openUrl

method Available since 1.0.0

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 Type Validation Notes
url string Required Url to open


Code example

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

initHapiExpress

method Available since 1.0.0

initHapiExpress

Creates an instance of Hapi.

Parameters

Parameter Type Validation Notes
client_id string Required A unique identifier of your system to group operations
ssk string Required The shared secret key to authorize the operations
auto_return Boolean Required 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);