Introduction

Introducing the Revolutionary Handpoint Cloud SDK: Seamlessly integrate card present payments into any cloud software

Use the Handpoint Cloud SDK to integrate leading smartpos terminals with your cloud software. The Handpoint Cloud SDK is a simple javascript interface running in your web application that acts as a bridge between the web browser and the payment terminal, while shielding your software from card data. It is seamless to integrate, keeps all card data out of your system, works with every platform, and lets you use the best Android terminals on the market.

Complete your integration in just three steps: Initiate the interface, choose the terminal, and start the sale. It is as simple as it sounds. The only thing you need is a valid API key to initialize the SDK. You even get a list of terminals to which you can connect. Simply execute the operation, and within seconds you’ll get back the transaction result and receipt in your software all while you monitor the transaction status. The Handpoint Cloud SDK seamlessly starts and manages the entire P2PE transaction with the payment terminal, minimizing hassle for you and maximizing reliability, security, and control.

For your merchants, the terminal setup is easier than a standalone. A merchant connects the terminal to their network, just like a smartphone, authenticates his/her account, and it simply works -- your software then control the terminal from anywhere in the world, and your merchants have secure, reliable, intuitive payments.

version 1.0.0

Available Soon!

API Overview

This API flow shows how easy it is to add card present payments to your cloud application. The interaction between your cloud application and the Handpoint Cloud SDK is simple and streamlined. The Handpoint Cloud SDK takes care of all of the communication with the terminal. The status messages are received in the WEB APP via the callback function defined in the Financial Operation requests call. That’s it.

The Handpoint Cloud SDK shields your software from all sensitive cardholder data. With Handpoint Cloud SDK, the transaction request goes from your software to Handpoint in the cloud. We steer the terminal from the cloud. All of the results come to your software via Handpoint in the cloud.


Configuration

Getting started with the SDK is fast and easy. Simply download the Javascript SDK from (url to download JS SDK available soon). Request a valid API key to start using the SDK and all of its functionalities. Initialize the SDK with your API key "init('API KEY')" and receive the list of devices available to perform the sale.

Sandbox

Get started today with our sandbox. You can generate sample transactions and test the experience right in your browser. Check it at: http://www.handpoint.com/experimental/cloudpos. Our sandbox couples as a terminal simulator and makes it simple for you to start testing right away, even if you don’t yet have a terminal available.

To get started, enter your Handpoint API key in the box labeled “CLOUDPOS KEY”. This will automatically populate the “DEVICES” box with the list of devices that are assigned to you. If the Handpoint API key that you enter is not valid, an error message will appear in the “RESPONSES” panel on the right side of the simulator screen.

Before you can begin any further testing, you first must select the device that you will be using. In the DEVICES list, you will see both the real terminals assigned to you (listed by serial number), as well as simulated devices. You can choose any device to test with. Serial numbers for the simulated devices alway have this format: 999999xxxxx-XXXX. Choose a simulated terminal if you do not have access to a real device or if you just want to see simulated behavior. Your can refresh the DEVICES list by clicking the refresh button on the right side of the DEVICES box.

Once you have selected a device, the DEVICES box will be disabled, and the rest of the sandbox will be enabled. With your selected device, you can simulate a number of operations, including:

  • sale
  • sale and tokenize
  • refund
  • tokenize card
  • reversal sale
  • reversal refund

For each operation used, responses will appear in the RESPONSES panel, whether the operation was a success or resulted in an error. To change to another device, use the disconnect button in the right panel. Once the disconnect button has been clicked, the DEVICES box will be enabled again, allowing you to choose another device and continue testing.

PLEASE NOTE: The simulator is for testing purposes only. To complete a full integration you will need to order a test payment terminal.

Processing Payments Simulation

Test transactions are conducted against a test server which is designed to simulate the behavior of an acquiring bank without moving any funds. As with every Handpoint terminal, sensitive card data is fully encrypted.

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
If you are using the simulator you can test these behaviors with additional cardholder variables.

Simply use the hundreds place and thousands place in the trigger amount.
- Enter a hundreds value to simulate various card brands: 1=VISA, 2=DISCOVER, 3=MASTERCARD, 4=AMEX
- Enter a thousands value to simulate the response for verification methods: 1=PIN, 2=SIGNATURE

For example, 2337.84 will respond with a “Not Authorized” operation (trigger amount = 37.84) for the Mastercard card scheme (hundreds = 3) and signature verification method (thousands = 2).

Any other values will behave as normal authorized operations.

Quick Integration Test

This js script sample shows how you can integrate your solution with Handpoint Cloud SDK to perform a product sale in three quick and simple SDK calls:

1) Request your test configuration (apiKey and deviceName constants) from Handpoint and set them in your web application
2) Download Handpoint.js from (url to download JS SDK available soon)
3) In the same directory, copy both Handpoint.js and the code below in an html file.
4) Open the html file in the browser and see test transactions immediately

SIMPLE, FAST, and EASY

<!doctype html>
<html>

<head>
  <title>Handpoint SDK Trial Integration</title>
  <script src="Handpoint.js"></script>
</head>

<body>
  <script>
    var hp = new Handpoint()
    //************* Test configuration *************//
    var apiKey = 'CT7MQ6X-H41MA3H-JNP3ZPC-W2GYCME';
    var deviceName = '0821032397-PAXA920';
    //*********************************************//
    hp.init(apiKey).then(
      response1 => {
        console.log('Successful initialization')
        document.writeln('Successful initialization<br />')
        hp.connect(deviceName).then(
          response2 => {
            console.log('Successful Connection to device [' + deviceName + ']');
            document.writeln('Successful Connection to device [' + deviceName + ']<br />')
            console.log('Executing sale');
            document.writeln('Executing sale<br />')
            hp.sale('10', 'EUR').then(
              response3 => {
                console.log('Successful sale');
                document.writeln('Successful sale<br />');
                hp.disconnect(deviceName).then(
                  response3 => {
                    console.log('Successful disconnection from device [' + deviceName + ']')
                    document.writeln('Successful disconnection from device [' + deviceName + ']<br />')
                  }
                ).catch(
                  error => console.log('Disconnection to device [' + deviceName + '] Failed -> ' + JSON.stringify(error))
                );
              }
            ).catch(
              error => console.log('Sale Failed -> ' + JSON.stringify(error))
            );
          }
        ).catch(
          error => console.log('Connection to device [' + deviceName + '] Failed -> ' + JSON.stringify(error))
        );
      }
    ).catch(
      error => console.log('Initialization Failed -> ' + JSON.stringify(error))
    );
  </script>
</body>

</html>

Methods

Initialize

method Available since 1.0.0

Initialize

Initializes the Cloud SDK and returns the list of payment terminals associated with the account

Parameters

Parameter Notes
API_key *
string
The Actor API key


Returns

Devices
List of Device objects

Code example

Handpoint.init('E0JJ8VC-JTR4XZP-GK3YVHY-3VYAA99');

Connect

method Available since 1.0.0

Connect

Connect the Cloud SDK to a payment terminal

Parameters

Parameter Notes
device_name *
string
The target payment terminal to connect to. The device_name is returned in the Device object of the init call.


Returns

Connection Result
200 code for OK - 403 code for NOK

Code example

Handpoint.connect('1234263-TYPE1');

Disconnect

method Available since 1.0.0

Disconnect

Disconnect the Cloud SDK from a payment terminal

Parameters

Parameter Notes
device_name *
string
The target payment terminal to disconnect from. The device_name is returned in the Device object of the init call.


Returns

Connection Result
'Disconnected' message for OK - 'ERROR disconnecting' message for NOK

Code example

Handpoint.disconnect('1234263-TYPE1');

Sale

method Available since 1.0.0

Sale

A sale initiates a payment operation to the card reader. In its simplest form, you only have to pass the amount and currency as parameters.

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
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Sale Response
A Financial Response object

Code example

Handpoint.sale('1000', 'USD', function (stat) {
  console.log('Transaction Status received -> '+ stat.message) 
});

SaleAndTokenization

method Available since 1.0.0

SaleAndTokenization

A sale which both authorizes the transaction and returns a token representing the card. This feature is not available for all acquirers. Please check with Handpoint to know if tokenization is supported for your acquirer of choice.

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
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Sale and Tokenization Response
A Financial Response object

Code example

Handpoint.saleAndTokenization('1000', 'USD', CallbackFunction(stat){...});

SaleReversal

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 its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters

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 of the original sale authorizationt
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Sale Reversal Response
A Financial Response object

Code example

Handpoint.saleReversal('1000', 'USD', '12345', CallbackFunction(stat){...});

Refund

method Available since 1.0.0

Refund

A refund initiates a refund operation to the payment terminal. This operation moves funds from the merchant account to the cardholder´s credit card. In its simplest form, you only have to pass the amount and currency as parameters.

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
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Refund Response
A Financial Response object

Code example

Handpoint.refund('1000', 'USD', CallbackFunction(stat){...});

RefundReversal

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 its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters.

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 of the original refund authorization
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Refund Reversal Response
A Financial Response object

Code example

Handpoint.refundReversal('1000', 'USD', '12345', CallbackFunction(stat){...});

TokenizeCard

method Available since 1.0.0

TokenizeCard

Returns a token for the card. This feature is not available for all acquirers. Please check with Handpoint to know if tokenization is supported for your acquirer of choice

Parameters

Parameter Notes
callback_function *
string
Callback function to subscribe to the transaction status updates.


Returns

Tokenize Card Response
A Financial Response object

Code example

Handpoint.tokenizeCard(CallbackFunction(stat){...});

Objects

Device

object Available since 1.0.0

Device

An object to store the information about the payment terminal you are working with. ALL values are REQUIRED

Properties

Property Description
merchant_id_alpha
String
Merchant unique identifier to which the device is associated
serial_number
String
Device serial number
ssk
String
Device shared secret key to authorize the operations.
terminal_type
String
Device type
device_name
String
Device name composed with serial_number - terminal_type

Code example

{
       "merchant_id_alpha": "Test_Merchant",
       "serial_number": "614004878",
       "ssk": "74817EA5C63437ADE7AA3A5401",
       "terminal_type": "PAXA920",
       "device_name": "0821032395-PAXA920"
}

Financial Response Object

object Available since 1.0.0

Financial Response

The response object is sent back from the payment terminal to your application and contains the transaction result. 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":object pairs.

Properties

Property Description
authorisationCode
String
The transaction authorization code, as given by the system.
budgetNumber
String
The budget number can be used to split payments over several months.
cardEntryType
CardEntryType
The card data acquisition type.
cardSchemeName
String
The card, reported, scheme name.
cardToken
String
Gets the card token if it's available, null otherwise.
cardTypeId
String
The card type id is an identifier inside the Handpoint gateway which represents what kind of card was used.
chipTransactionReport
String
If present, a full EMV report by the card reader on the Card and Terminal involved in the transaction.
currency
Currency
The currency code used for the transaction.
customerReceipt
String
Customer receipt of transaction from card reader in html format.
customerReference
String
echo of the optional customerReference parameter sent in the transaction request.
deviceStatus
DeviceStatus
The status of the payment terminal
dueAmount
String
If there's still a part of the amount to be paid.
eFTTimestamp
String
The date and time of the transaction, in ISO format (YYYYMMDDHHmmSS).
eFTTransactionID
String
The EFT reference, given by the system, to make the transaction unique.
errorMessage
String
Description of the error, if any.
ExpiryDateMMYY
String
The expiry date of the card used for the operation.
finStatus
FinancialStatus
The result of the transaction.
gratuityAmount
String
The gratuity amount entered by the cardholder, if any.
gratuityPercentage
String
The gratuity amount, as a percentage of the requested amount.
isRecoveredTransaction
boolean
This flag is true if the transaction result is from a previous transaction which failed to get sent from the card reader, false otherwise. In the case that the communication between the device and the card reader breaks down, the card reader will attempt to send the result of the previous transaction as an immediate reply when the next transaction is started. If this happens the transaction is flagged as a RecoveredTransaction. This should be displayed very well in the UI since this is *NOT* the result from the transaction just started.
maskedCardNumber
String
The masked card number used in the operation.
merchantReceipt
String
Merchant receipt of transaction from card reader in html format.
originalEFTTransactionID
String
The original EFT reference, given by the POS, as part of a VOID_SALE or a VOID_REFUND transaction.
requestedAmount
String
The amount requested by the point of sale (POS), as requested by the POS (i.e. no decimal point).
statusMessage
String
A human readable description for the returned Status.
totalAmount
String
The total of the gratuity and requested amount.
transactionID
String
The transaction number used for this transaction, as maintained by the electronic fund transfer (EFT) Client.
type
TransactionType
The type of financial transaction performed.
verificationMethod
VerificationMethod
The cardholder verification method (CVM).

Code example

{
  "authorisationCode": "",
  "budgetNumber": "",
  "cardEntryType": "UNDEFINED",
  "cardSchemeName": "",
  "cardToken": "",
  "cardTypeId": "",
  "chipTransactionReport": "",
  "currency": "Unknown",
  "customerReceipt": "",
  "customerReference": "",
  "deviceStatus": {
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "0821032397",
    "statusMessage": "Card reader time out"
  },
  "dueAmount": 0,
  "eFTTimestamp": "Oct 28, 2019 15:22:32",
  "eFTTransactionID": "",
  "errorMessage": "",
  "expiryDateMMYY": "",
  "finStatus": "CANCELLED",
  "gratuityAmount": 0,
  "gratuityPercentage": 0,
  "isRecoveredTransaction": false,
  "maskedCardNumber": "",
  "merchantReceipt": "",
  "originalEFTTransactionID": "",
  "requestedAmount": 0,
  "statusMessage": "Card reader time out",
  "totalAmount": 0,
  "transactionID": "",
  "type": "UNDEFINED",
  "verificationMethod": "NOT_REQUIRED"
}

Transaction Status

object Available since 1.0.0

TransactionStatus

A class that holds the device status. This is the object that will be recieved in the financial operation callback functions

Properties

Property Description
deviceStatus
DeviceStatus
OPTIONAL - The status of the payment terminal.
isCancelAllowed
boolean
defines is a transaction can be cancelled or not.
message
String
Human readable status message.
status
status
An enum containing information about the status of the transaction.

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 TOKENIZE_CARD

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

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 PARTIAL_APPROVAL

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 Status

object Available since 1.0.0

DeviceStatus

A class that holds the device status.

Properties

Property Description
SerialNumber
String
The serial number of the device
BatteryStatus
String
The battery status in percentages of a device
BatterymV
String
The battery milli volts of a device
BatteryCharging
String
The battery charging status of a device
ExternalPower
String
The status of an external power of a device
ApplicationName
String
The application name used on a device
ApplicationVersion
String
The application version number used on a device
bluetoothName
String
The bluetooth interface name used on a device
statusMessage
String
Device human readable status message

Code example

{
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "0821032397",
    "statusMessage": "Card reader time out"
}

Card Entry Type

enum Available since 1.0.0

CardEntryType

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

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