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.
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.
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 |
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>
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>
Name | Type | Description |
---|---|---|
action | object | Required. Contains the transaction type and relevant parameters |
client | object | Required. Contains information specific to the client setup |
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... |
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. |
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. |
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 |
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.
{ "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" : {}
}
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. |
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. |
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.
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);
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.
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. |
Hapi.urlForSaleReversal('1000', 'USD', '1234' {'extra-value':'some info'}, 'http://callback.com');
urlForScanner
Constructs the URL needed for opening the express app and starting scanning.
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. |
Hapi.urlForScanner(false, false, true, 0, {'extra-value':'some info'}, 'http://callback.com');
urlForSaleAndTokenizeCard
Constructs the URL needed for opening the express app and starting a saleAndTokenizeCard.
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. |
Hapi.urlForSaleAndTokenizeCard('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');
urlForSale
Constructs the URL needed for opening the express app and starting a sale.
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. |
Hapi.urlForSale('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');
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.
Parameter | Notes |
---|---|
url *
string |
Url to open |
Hapi.openURL('handpoint://express/v1/?data=')
urlForRefund
Constructs the URL needed for opening the express app and starting a refund operation.
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. |
Hapi.urlForRefund('1000', 'USD', {'extra-value':'some info'}, 'http://callback.com');
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.
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. |
Hapi.urlForRefundReversal('1000', 'USD', '1234' {'extra-value':'some info'}, 'http://callback.com');
initHapiExpress
Creates an instance of Hapi.
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. |
initHapiExpress('hapi-tests', '010203040050606', false);