Terminal Management

Initialize

Initialize Method

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

Parameters

Parameter	Notes
API_key Required string	The API key provided by Handpoint for the merchant.
dev_or_prod_environment Required boolean	Value which defines if the JS SDK is targeting the development environment (true -> cloud.handpoint.io) or the production environment (false -> cloud.handpoint.com).
recovery_EoT_callback Required promise	Promise collecting the pending transaction results which couldn't be delivered to the web application during the execution of the transaction, for example if the network connection became unstable. The callback input parameter is a TransactionResult object. When the promise is resolved the JS SDK will send the ACK to the payment terminal to mark the result as recovered and the device will delete it from its storage. If the promise is rejected, the device will resend the TransactionResult until the promise is correctly resolved and the ACK sent to the payment terminal. The sdk has a 5 second window for the promise to be resolved

Code example

Handpoint.init('API KEY', true, (pendingEoT) => {
 console.log('Recovered Transaction -> ' + JSON.stringify(pendingEoT);
 return handleTransactionResultPromise(pendingEoT);
})
 
// For simple or sync operations you may return a resolved Promise. 
Handpoint.init('API KEY', true, (pendingEoT) => {
 console.log('Recovered Transaction -> ' + JSON.stringify(pendingEoT);
 return Promise.resolve();
})

Returns

Parameter	Notes
Devices	List of device objects.

Connect

Connect Method

Connects the Javascript SDK to a payment terminal.

Parameters

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

Code example

Handpoint.connect('0821330373-PAXA920');

Returns

Parameter	Notes
Connection Result	200 code for OK 403 code for NOK

Disconnect

Disconnect Method

Disconnects the Javascript SDK from a payment terminal.

Parameters

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

Code example

Handpoint.connect('1850345672-PAXA920PRO');

Returns

Parameter	Notes
Connection Result	Disconnected message for OK ERROR disconnecting message for NOK

Stop Listening Device

StopListeningDevice Method

This operation stops the connection between your application and the payment terminal. It stops listening to transaction events and resets the connection with the card reader.

Code example

//Stop Listening to Events 
Handpoint.stopListeningDevice();

Stop Current Transaction

StopCurrentTransaction Method

Operation used to stop the current transaction. The transaction can only be stopped at specific stages of payment processing, for example a transaction can not be stopped when the card is being read but can be stopped when waiting for the cardholder to initially insert a card.

Code example

Handpoint.stopCurrentTransaction();

Returns

Parameter	Notes
Promise Successful Response	{finStatus: CANCELLED, statusMessage: 'Operation stopped'}
Promise Error Response	{finStatus: FAILED, errorMessage: 'Unable to stop current transaction'}
Promise Error Response	{ finStatus: FAILED, errorMessage: 'No response received from the card reader' }

Print Receipt

PrintReceipt Method

Print on demand functionality allowing the merchant to print any HTML formatted receipt. It is possible to print images or barcodes as well as passing directly a URL to the printReceipt function. A bitmap can also be printed, in order to do so it needs to be rendered as an image and inserted into the html.

tip

The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.

Parameters

Parameter	Notes
receipt Required string	HTML receipt or url to locate the receipt, it can be found in the response of a financial operation, in the fields merchantReceipt or customerReceipt. The receipt must match the following HTML Print Format.
callback_function Required string	Callback function to subscribe to the transaction status updates.

Code example

Handpoint.printReceipt('https://location_of_receipt_container.com/receipt_location', CallbackFunction(stat){...});

var htmlReceipt = '[...] HTML receipt [...]'

Handpoint.printReceipt(htmlReceipt, CallbackFunction(stat){...});

Returns

Parameter	Notes
Print Receipt Response	A specific status object which describes the printing action (PrinterOutOfPaper, ErrorConnectingToPrinter or ReceiptPrintSuccess)

Ping Device

PingDevice Method

This operation will ping the terminal to confirm if it is online. The promise is correctly resolved if the device is online and successfully answers to the ping

Parameters

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

Code example

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

Returns

Parameter	Notes
Device Status	A Device Status object.

Update

Update Method

Triggers a terminal software and config update.

Parameters

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

Code example

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

Returns

Parameter	Notes
Update Response	A financial response object.