cordova-plugin-handpoint v1.8.0

Cordova Handpoint SDK Plugin

Cross-platform Handpoint SDK for Cordova. This plugin is intended to enable the access to Handpoint Card Readers from any cross-platform application built over Cordova.

You might want to take a look at the Ionic 2 starter application to see a fully functional app using the plugin.

Installation

You can install handpoint plugin with Cordova CLI, from npm:

cordova plugin add cordova-plugin-handpoint

Overview

The plugin creates the object cordova.plugins.Handpoint with the following public methods and properties:

Properties

Methods

Quick start

• 1. Setup the Handpoint SDK Singleton with your shared secret. The shared secret is a key provided by Handpoint when you get your account that enables you to perform live operations with the card reader:

  // Init Handpoint SDK 
  cordova.plugins.Handpoint.setup({}, () => {
    // SDK initialization succeed
    // set shared secret
    cordova.plugins.Handpoint.setSharedSecret({
      sharedSecret: '0102030405060708091011121314151617181920212223242526272829303132'
    }, () => { 
      // Initialization completed
    }, (error) => {
      // Set shared secret failed        
    });

  }, (error) => {
    // SDK initialization failed  
  });

• 2. Configure event handler to receive async notifications from the Card Reader. Most of the methods of the SDK are asynchronous. Once you send the operation to the Card reader, you will be notified of the status through the event handler function. See Event Handling section.

// Configure event handler
cordova.plugins.Handpoint.eventHandler(function (event) {
  // Event handling goes here
  // event.event contains the type of event 
  // event.data contains the event payload
  console.log(event);
}, function (error) {
  // Error in event handler setup
  console.log(error);
});   

• 3. Scan devices: This is a very expensive operation and you should consider to cache the result in local storage and call it again only if user has paired a new device. IMPORTANT NOTE: You need to ask the user to pair the device before it appears in the results:

cordova.plugins.Handpoint.listDevices({
  connectionMethod:  cordova.plugins.Handpoint.ConnectionMethod.BLUETOOTH
}, function() {
  // Call succeed. You will receive the list of devices in the event handler declared above. Event 'deviceDiscoveryFinished'
}, function() {
  // Call failed
});

• 4. Connect to one the devices scanned above:

cordova.plugins.Handpoint.connect({
  device: {
    name: device.name,
    address: device.address,
    port: "1",
    connectionMethod: cordova.plugins.Handpoint.ConnectionMethod.BLUETOOTH
  }
}, (result) => {
  // Nothing to do. Wait for Connected event or timeout
}, (error) => {
  // Error connecting to device
});

• 5. Start transaction:

cordova.plugins.Handpoint.sale({
  amount: 120,
  currency: cordova.plugins.Handpoint.Currency.ISK,
}, function() {
  // Success. Wait for currentTransactionStatus events
}, function() {
  // Error
});

• 6. Wait for currentTransactionStatus events. F. ex. you might want to listen to currentTransactionStatus event to notify user of different Card Reader statuses, and of course endOfTransaction event to know the final result of the transaction. See Event Handling section.

// Handler declared in second step
cordova.plugins.Handpoint.eventHandler(function (event) {
  if (event.event == 'currentTransactionStatus') {
    // Show status to the user
    switch (event.data.info.status) {
      case "WaitingForCard": 
      case "WaitingForCardRemoval": 
      case "TipInput":
      case "WaitingCustomerReceipt":
      case "PrintingMerchantReceipt":
      case "PrintingCustomerReceipt":
      case "WaitingSignature":
      case "ApplicationSelection":
      case "AmountValidation":
      case "AccountTypeSelection":
      case "PaymentCodeSelection":
      case "WaitingHostConnect":
      case "WaitingHostSend":
      case "WaitingHostReceive":
      case "WaitingHostDisconnect":
      case "WaitingHostMessageRequest":
      case "WaitingHostMessageResponse":
      case "PinInputComplete":
      case "PinInput":
    }
  } 
  // Wait for transaction end
  else if (event.event == 'endOfTransaction') { 
    switch (event.data.transactionResult.finStatus) {
      case "AUTHORISED": // Succeed. Inspect event.data.transactionResult for details
        break;
      case "DECLINED": // Failed
      case "CANCELLED":
      case "FAILED":
        break;
    }
  }
});

API Documentation

Properties

ConnectionMethod

Enum. containing supported connection methods. You have to pass the ConnectionMethod when searching for devices or connect to one of them:

Currency

Enum. containing ISO 4217 codes. f.ex. cordova.plugins.Handpoint.Currency.ISK evaluates as 352. You need to speficy the currency in financial transactions sale, refund, saleReversal and refundReversal:

LogLevel

Enum. containing supported logging levels:

Methods

All the methods of the plugin are asynchronous and return the result of the execution either to a success or an error callback: cordova.plugins.Handpoint.methodName([config], successCallback, errorCallback)

setup

Initializes the Handpoint SDK. Don't forget to execute it before trying to use the SDK:

cordova.plugins.Handpoint.setup({}, successCallback, errorCallback)

setSharedSecret

Validates the app for this session, thus enabling financial transactions. Don't forget to set shared secret before connect to a device:

cordova.plugins.Handpoint.setSharedSecret({ sharedSecret: '0102030405060708091011121314151617181920212223242526272829303132' }, successCallback, errorCallback)

eventHandler

Sets up the SDK event handler. See Event Handling section.

cordova.plugins.Handpoint.eventHandler(function(data) {
  // data.event contains the event name
  // data.data contains the event payload
}, errorCallback)

tokenizeCard

A tokenizeCard returns the tokenized version of the card used if successful (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice)

cordova.plugins.Handpoint.tokenizeCard({}, successCallback, errorCallback)

sale

A sale initiates a payment operation to the card reader.

cordova.plugins.Handpoint.sale({
  amount: 1000, // Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
  currency: cordova.plugins.Handpoint.Currency.GBP
}, successCallback, errorCallback)

saleAndTokenizeCard

A saleAndTokenizeCard initiates a payment operation and card tokenization request to the card reader

cordova.plugins.Handpoint.saleAndTokenizeCard({
  amount: 1000, // Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
  currency: cordova.plugins.Handpoint.Currency.GBP
}, successCallback, errorCallback)

refund

A refund initiates a refund operation to the card reader.

cordova.plugins.Handpoint.refund({
  amount: 1000, // Amount of funds to refund - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
  currency: cordova.plugins.Handpoint.Currency.GBP
}, successCallback, errorCallback)

saleReversal

A sale Reversal, also called sale VOID allows the user to reverse a previous sale operation.

cordova.plugins.Handpoint.saleReversal({
  amount: 1000, // Amount of funds to reverse - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
  currency: cordova.plugins.Handpoint.Currency.GBP,
  originalTransactionID: result.transactionResult.eFTTransactionID // where result is the endOfTransaction event payload
}, successCallback, errorCallback)

refundReversal

A Refund Reversal, also called Refund VOID allows the merchant to reverse a previous refund operation.

cordova.plugins.Handpoint.refundReversal({
  amount: 1000, // Amount of funds to reverse - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
  currency: cordova.plugins.Handpoint.Currency.GBP,
  originalTransactionID: result.transactionResult.eFTTransactionID // where result is the endOfTransaction event payload
}, successCallback, errorCallback)

enableScanner

Enable Scanner allows the merchant to use the QR / Barcode scanner (where available)

cordova.plugins.Handpoint.enableScanner({
  multiScan: false,
  autoScan: false,
  resultsGrouped: true,
  timeout: 0
}, successCallback, errorCallback)

signatureResult

When a signatureRequired event is fired, the merchant is required to ask the cardholder for signature and approve or decline it. After that you can execute this method to inform on the result

cordova.plugins.Handpoint.signatureResult({
  accepted: true
}, successCallback, errorCallback)

listDevices

Starts the search for devices to connect to with the specified ConnectionMethod.

cordova.plugins.Handpoint.listDevices({
  connectionMethod: cordova.plugins.Handpoint.ConnectionMethod.SIMULATOR
}, successCallback, errorCallback)

connect

Configures the device as the preferred device and tries to connect to it.

cordova.plugins.Handpoint.connect({
  device: device // One of the devices returned from listDevices operation
}, successCallback, errorCallback)

disconnect

Disconnect will stop the active connection

cordova.plugins.Handpoint.disconnect({
  device: device // One of the devices returned from listDevices operation
}, successCallback, errorCallback)

getPendingTransaction

In the case of a communication failure between the device and the SDK a TransactionResult might have not been delivered to the SDK. This function fetches a pending TransactionResult (which contains receipts) from the device, if any.

cordova.plugins.Handpoint.getPendingTransaction({}, successCallback, errorCallback)

update

The update operation checks for update to the current card reader and initiates an update if needed. The update can either be a software update or a configuration update.

cordova.plugins.Handpoint.update({}, successCallback, errorCallback)

setLogLevel

Sets the log level for both the card reader and the SDK.

cordova.plugins.Handpoint.setLogLevel({
  level: cordova.plugins.Handpoint.LogLevel.Debug
}, successCallback, errorCallback)

getDeviceLogs

Fetches the logs from the device and reports them to the deviceLogsReady event.

cordova.plugins.Handpoint.getDeviceLogs({}, successCallback, errorCallback)

getSDKVersion

Returns the underlying SDK version in the success callback.

cordova.plugins.Handpoint.getSDKVersion({}, (version) => {
  console.log(version);
}, errorCallback)

Event Handling

As explained before, all the methods of the plugin are asynchronous and return the result of the execution either to a success or an error callback.

If you don't want to deal with callbacks and you prefer to turn Callbacks into Promises you might want to publish the events received in the callback function passed to cordova.plugins.Handpoint.eventHandler method to a publish-subscribe style event system and then encapsulate the event handling logic in an SDK wrapper module.

Let's suppose that you want to implement a sale which returns a Promise that resolves when the transaction is completed, or rejects when it is failed.

First we need to publish sale related events to our event system:

cordova.plugins.Handpoint.eventHandler(function (event) {
  …
  // Publish event
  if (event.event == 'endOfTransaction') {
    events.publish("handpoint:" + event.event + ":" + event.data.transactionResult.finStatus, event.data);
  }
  …
}, function (error) {
  …
});

Now we are publishing Handpoint events as handpoint:endOfTransaction:AUTHORISED, handpoint:endOfTransaction:DECLINED, etc.

And finally encapsulate the Handpoint SDK sale method in a function that returns a Promise which deals with event subscriptions:

function salePromise(): Promise<any> {
  return new Promise((resolve, reject) => {
    cordova.plugins.Handpoint.sale(params, ()=> {
      // Subscribe to success events and resolve the promise: handpoint:endOfTransaction:AUTHORISED
      … 
      successEvents.subscribe((result) => {
        resolve(result);
      });
      // Subscribe to error events and reject the promise: handpoint:endOfTransaction:DECLINE handpoint:endOfTransaction:FAILED handpoint:endOfTransaction:CANCELLED
      … 
      errorEvents.subscribe((result) => {
        reject(result);
      });
      // Clean up and unsubscribe
      …
    }, (error) => {
      reject(error);
    });
  })
}

NOTE: the example above is pseudocode, you have a fully implemented wrapper here.