You are currently viewing the documentation for version

API overview

How to implement a Sale Transaction

The below flow chart shows the interaction between the SDK, the payment terminal and your application. The orange arrows represent methods (requests) that need to be invoked to communicate with the Handpoint SDK's. The dark arrows represent events that need to be integrated in your code in order to retrieve information from the SDK´s and the card reader.


How to implement a Sale Transaction with Recovery feature

At some point, the connection between the SDK and the card reader can become unstable. For example, the Bluetooth connection can be cut in the middle of a sale transaction if the smartphone runs out of battery. If this happens, you need to have implemented the “transaction recovery feature” in order to get the receipts from the previous transaction and knowing if it was successful despite the connection problem.



Supported functionality

  • Discovery of remote BT devices.
  • Connect to remote BT device.
  • Physical connection to HiPro external accessory.
  • Automatic or manual reconnection to the card reader.
  • Executing financial transaction.
  • Reporting status of transactions.
  • Control and access to device logs.
  • Barcode scanner with HiPro card readers.
  • Limited card reader simulation.

Processing Payments Simulation

Your test payments are sent against a test server on the Handpoint side which simulates the behavior of an acquiring bank. Funds are not moved and sensitive data from the card is fully encrypted. You can 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


Transactions

Sale

method Available since 3.2.4

sale

A sale initiates a payment operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters.

Parameters

Parameter Notes
amount *
BigInteger		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
Currency		 Currency of the charge
map
Map		 A map including extra optional transaction parameters.
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry').
signatureRequired
Invoked if card verification requires signature.
endOfTransaction
Invoked when the card reader finishes processing the transaction.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Initiate a sale for 10.00 in Great British Pounds
api.sale(new BigInteger("1000"),Currency.GBP);

Sale And Tokenize Card

method Available since 4.2.0

saleAndTokenizeCard

A sale that 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)

Parameters

Parameter Notes
amount *
BigInteger		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
Currency		 Currency of the charge
map
Map		 A map including extra optional transaction parameters.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry').
signatureRequired
Invoked if card verification requires signature.
endOfTransaction
Invoked when the card reader finishes processing the transaction.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Initiate a sale for 10.00 in Great British Pounds
api.saleAndTokenizeCard(new BigInteger("1000"),Currency.GBP);

Sale Reversal

method Available since 3.2.4

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 it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter Notes
amount *
BigInteger		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
Currency		 Currency of the charge
originalTransactionID *
String		 As received from the card reader (EFTTransactionID)
map
Map		 A map including extra optional transaction parameters.
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry').
signatureRequired
Invoked if card verification requires signature.
endOfTransaction
Invoked when the card reader finishes processing the transaction.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Initiate a reversal for 10.00 in Great British Pounds
api.saleReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000");

Refund

method Available since 3.2.4

refund

A refund initiates a refund operation to the card reader. This operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters.

Parameters

Parameter Notes
amount *
BigInteger		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
Currency		 Currency of the charge
map
Map		 A map including extra optional transaction parameters.
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired
Invoked if card verification requires signature.
endOfTransaction
Invoked when the card reader finishes processing the transaction

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Initiate a refund for 10.00 in Great British Pounds
api.refund(new BigInteger("1000"),Currency.GBP);

Refund reversal

method Available since 3.2.4

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 it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter Notes
amount *
BigInteger		 Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency *
Currency		 Currency of the charge
originalTransactionID *
String		 As received from the card reader (EFTTransactionID)
map
Map		 A map including extra optional transaction parameters.
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry')
signatureRequired
Invoked if card verification requires signature.
endOfTransaction
Invoked when the card reader finishes processing the transaction

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Initiate a refund reversal for 10.00 in Great British Pounds
api.refundReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000");

Signature result

method Available since 3.2.4

signatureResult

A signatureRequired event is invoked during transaction when signature verification is needed (f.ex when payment is done with a magstripe card). The merchant is required to ask the cardholder for signature and approve (or decline) the signature. signatureResult tells the card reader if the signature was approved by passing the value true in the method. To decline a signature event then false should be passed to the card reader.

Parameters

Parameter Notes
accepted *
Boolean		 pass true if merchant accepts customer signature
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

currentTransactionStatus
Invoked during a transaction, it fetches statuses coming from the card reader (ex : 'waiting for card' or 'waiting for PIN entry').
endOfTransaction
Invoked when the card reader finishes processing the transaction.

Returns

Boolean
true if the operation was successfully sent to device.

Code example

//Approves signature automatically in signatureRequired event
@Override
public void signatureRequired(SignatureRequest signatureRequest, Device device){
	api.signatureResult(true);
}

Tip Adjustment

method Available since 3.3.0

TipAdjustment

A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled by the processor at the end of the day.
Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and VANTIV.

Dependencies:
The code example provided depends on RxJava, take a look a their documentation to see how to easily include this dependency in your android project. If you do not want to use RxJava or any additional dependencies then AsyncTask, provided by android, can be used instead for this asynchronous processing. Still we recommend using RxJava as it improves readability and maintainability.

Parameters

Parameter Notes
tipAmount *
BigDecimal		 Tip amount added to the original (base) transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
originalTransactionID *
String		 Unique id of the original sale transaction as received from the card reader (EFTTransactionID)


Returns

FinancialStatus

Result of the tip adjustment transaction, it returns a FinancialStatus, the possible values are :

- FinancialStatus.AUTHORISED (tip adjustment approved by the processor)
- FinancialStatus.FAILED (system error or timeout)
- FinancialStatus.DECLINED (tip adjustment declined by the processor)

If two tip adjustments are sent for the same sale transaction, the second tip adjustment will override the first one. In case the transaction fails (not declined) we recommend that you prompt the user of the POS to retry the adjustment.

Code example

Observable.fromCallable(new Callable() {
	@Override 
	public FinancialStatus call() throws Exception { 
		return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); 
	}
}) 
.subscribeOn(Schedulers.io()) 
.observeOn(AndroidSchedulers.mainThread()) 
.subscribe(new Consumer() { 
	@Override 
	public void accept(@NonNull FinancialStatus status) throws Exception {
		if (status == FinancialStatus.AUTHORISED) { 
			//SUCCESS
		} else if (status == FinancialStatus.DECLINED) {
			//DECLINED
		} else {
			//FAILED
	}
});

Device management

Disconnect

method Available since 3.2.4

disconnect

Disconnect will stop the active connection (and reconnection process). Please note that the method does NOT ignore the current state of the card reader. This means that if a disconnect is attempted during a transaction it will not be successful and the method will return false. If a transaction is not in progress the disconnect will take 1-3 seconds to successfully finish and will then return true.

Parameters

Parameter Notes
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

connectionStatusChanged
Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information.

Returns

Boolean
true if the operation was successful.

Code example

//Disconnect from current device
api.disconnect();

Request device logs

method Available since 3.2.4 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



getDeviceLogs

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

Parameters

Parameter Notes
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

deviceLogsReady
Invoked when hapi has finished downloading logs from the card reader.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Downloads logs from device
api.getDeviceLogs();

Get connection status

method Available since 4.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



getConnectionStatus

Returns the latest stored connection status.

Returns

ConnectionStatus
the current connection status

Code example

// Get current connection status
ConnectionStatus cs = api.getConnectionStatus();

Request device logs

method Available since 3.2.4 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



getDeviceLogs

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

Parameters

Parameter Notes
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

deviceLogsReady
Invoked when hapi has finished downloading logs from the card reader.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Downloads logs from device
api.getDeviceLogs();

Request pending transaction results

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



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. If no TransactionResult was pending a result will be delivered containing default fields. In order to receive only valid TransactionResults this function should only be called when pendingTransactionResult event is invoked or when HapiManager.isTransactionResultPending() is true. To receive events when a TransactionResult is pending on the device please add a Events.PendingResults listener.

Parameters

Parameter Notes
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

transactionResultReady
Invoked when hapi has finished fetching a TransactionResult from the device.

Returns

Boolean
true if the operation was successfully sent to the device

Code example

//Fetches a pending TransactionResult from a device
api.getPendingTransaction();

List Devices (search)

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



listDevices

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

Parameters

Parameter Notes
method *
ConnectionMethod		 The means of connection you intend to use to talk to the device. (Bluetooth, Cloud, Serial, USB, etc...)


Events invoked

deviceDiscoveryFinished
Invoked after the search is finished returning a list of the devices finished.

Code example

//Search for Bluetooth devices
api.listDevices(ConnectionMethod.BLUETOOTH);

Set logging level

method Available since 3.2.4

setLogLevel

Sets the log level (info, debug...) for both the payment terminal and the SDK.

Parameters

Parameter Notes
level *
LogLevel		 The desired log level. Can be LogLevel.None, LogLevel.Info, LogLevel.Full, LogLevel.Debug
device
Device		 This parameter specifies to the system which device should be used for the operations. If no device is supplied, the system will attempt to use a default one.


Events invoked

None
No events are invoked.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Sets the log level to info
api.setLogLevel(LogLevel.info);

Set parameter

method Available since 3.2.4 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



setParameter

Changes values of certain parameters on the card reader.

Parameters

Parameter Notes
param *
DeviceParameter		 The name of the parameter to change
value *
String		 New value of the parameter
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

None
No events are invoked.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Changes the bluetooth name of card reader
api.setParameter(DeviceParameter.BluetoothName, "OrangeCardReader");

Set shared secret

method Available since 3.2.4 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



setSharedSecret

Validates the app for this session, thus enabling financial transactions

Parameters

Parameter Notes
sharedSecret *
String		 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. However, if you're developing with a starter kit, the test shared secret is specified in the example
device
Device		 This parameter specifies to the system which device you want to use for the operations. If none is supplied the system will attempt to use a default device, if any.


Events invoked

None
No events invoked.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Sets the shared secret using the test key
api.setSharedSecret("0102030405060708091011121314151617181920212223242526272829303132");

Start monitoring connections

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



startMonitoringConnections

Starts a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with BLUETOOTH. In the case of BLUETOOTH the service will attempt to reconnect to the device three times, if unsuccessful the connection is considered Disconnected.

NOTE: you don't need to call this method explicitly since version 4.0.0.

Events invoked

connectionStatusChanged
Causes the connection manager to invoke this event with the appropriate information.

Returns

None
No information is returned.

Code example

//Starts the connection monitoring service
//app starts it's life-time
api.startMonitoringConnections();
...
//app ends its life-time
api.stopMonitoringConnections

Stop monitoring connections

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



stopMonitoringConnections

Stops a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with BLUETOOTH. In the case of BLUETOOTH the service will attempt to reconnect to the device three times, if unsuccessful the connection is considered Disconnected.

Events invoked

connectionStatusChanged
Causes the connection manager to invoke this event with the appropriate information.

Returns

None
No information is returned.

Code example

//Starts the connection monitoring service
//app starts it's life-time
api.startMonitoringConnections();
...
//app ends its life-time
api.stopMonitoringConnections

Update device

method Available since 3.2.4

update

The update operation checks for new software or configuration updates and initiates a download if required.

Parameters

Parameter Notes
device
Device		 This parameter specifies to the system which device should be used for the operations. If no device is supplied, the system will attempt to use a default one.


Events invoked

None
The merchant should be notified about the update process.

Returns

Boolean
true if the operation was successfully sent to device

Code example

//Check for card reader update
api.update();

Connect

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



useDevice

Configures the device as the preferred device and tries to connect to it. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed.

Parameters

Parameter Notes
device *
Device		 This parameter specifies to the system which device you want to use for the operations.


Events invoked

connectionStatusChanged
Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information.

Returns

Boolean
true if the operation was successful.

Code example

//Connect to a device
Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH);

api.useDevice(device);

Events

Device discovery finished

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



deviceDiscoveryFinished

deviceDiscoveryFinished event gets called when a device discovery has finished and returns a list of devices.

Parameters

Parameter Notes
device *
Device		 The device that is invoking the event


Subscribers Needed

addRequiredEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve the devices information.

Code example

//Receiving a list of connectable devices
List myListOfDevices = new List();
@Override
public void DeviceDiscoveryFinished(List devices)
{
	foreach(Device device in devices){		myListOfDevices.Add(device);
	}
}

Signature required

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



signatureRequired

signatureRequired event gets called when a card requires a signature instead of PIN entry and has two parameters, request and device.

Parameters

Parameter Notes
request *
SignatureRequest		 Holds the signature request
device *
Device		 The device that is invoking the event


Subscribers Needed

addRequiredEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve signature information.

Code example

@Override
public void signatureRequired(SignatureRequest signatureRequest, Device device) {
	signatureRequest.getMerchantReceipt();
	api.signatureResult(true);
}

End of transaction

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



endOfTransaction

endOfTransaction event gets called at the end of each transaction and has two parameters, result and device.

Parameters

Parameter Notes
result *
TransactionResult		 Holds the results for the transaction
device *
Device		 The device that is invoking the event


Subscribers Needed

addRequiredEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve transaction information.

Code example

@Override
public void endOfTransaction(TransactionResult transactionResult, Device device) {
	Log.d(App, transactionResult.getCustomerReceipt());
}

Connection status changed

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



connectionStatusChanged

connectionStatusChanged event gets called when the state of a card reader connection changes.

Parameters

Parameter Notes
status *
ConnectionStatus		 An enum containing the status code for the connection
device *
Device		 The device that is invoking the event


Subscribers Needed

addStatusNotificationEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve the different connection statuses (e.g : CONNECTED, DISCONNECTED...).

Code example

@Override
public void connectionStatusChanged(ConnectionStatus connectionStatus, Device device) {
	Log.d(App, connectionStatus.name());
}

Message logged

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



onMessageLogged

onMessageLogged event gets called for all log messages that are being logged. This is only intended for debugging.

Parameters

Parameter Notes
logLevel *
LogLevel		 An enum containing the log level
message *
String		 A String containing the current log message


Subscribers Needed

addLogEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve the different log messages.

Code example

@Override
public void onMessageLogged(LogLevel logLevel, String message){
	Log.d("API log", message);
}

Logs ready

method Available since 3.0.0 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



deviceLogsReady

DeviceLogsReady event gets called when the card reader logs requested by a call to getDeviceLogs() are ready. This Event is really useful if there has been a communication error between the card reader and the API (e.g : Bluetooth communication lost). After reconnecting, you can then fetch the card reader logs to the API.

Parameters

Parameter Notes
logs *
String		 String containing the current log
device *
Device		 The device that is invoking the event


Subscribers Needed

addLogEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve the card reader logs.

Code example

@Override
public void deviceLogsReady(String logs, Device device){
	Log.d("Device logs:", logs);
}

Pending transaction result

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



pendingTransactionResult

In the case of a communication failure between the device and the API a TransactionResult might have not been delivered to the API. This event is invoked when the device has a pending TransactionResult. This event might be invoked when reconnecting to a device after a communication failure during a transaction.

Parameters

Parameter Notes
device *
Device		 The device that is invoking the event


Subscribers Needed

addPendingResultsEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve information about pending results.

Code example

@Override
public void pendingTransactionResult(Device device){
	//Here you might want to call api.getPendingTransaction(); to receive the TransactionResult
}

Transaction result ready

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



transactionResultReady

In the case of a communication failure between the device and the API a TransactionResult might have not been delivered to the API. This event will be invoked after using hapi.getPendingTransaction();. When there is no pending transaction the TransactionResult will contain default/error fields and no receipts.

Parameters

Parameter Notes
result *
TransactionResult		 Holds the results for the transaction
device *
Device		 The device that is invoking the event


Subscribers Needed

addPendingResultsEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve information about pending results.

Code example

@Override
public void transactionResultReady(TransactionResult transactionResult, Device device){
	//Here you might want to do stuff to the transactionResult
}

Current transaction status

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



currentTransactionStatus

currentTransactionStatus event gets called when the state of an ongoing transaction changes.

Parameters

Parameter Notes
statusInfo *
StatusInfo		 An object containing information about the current transaction
device *
Device		 The device that is invoking the event


Subscribers Needed

addStatusNotificationEventHandler
This listener has to be implemented (preferably during initialisation) in order to retrieve the different states from the card reader (e.g : Waiting for card, Waiting for PIN entry...).

Code example

@Override
public void currentTransactionStatus(StatusInfo statusInfo, Device device) {
}

Events subscribers

Add Required Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



addRequiredEventHandler

Adds a listener so necessary information can be retrieved. Such as signature verification, receipts and list of devices. This listener fetches information from the following events : deviceDiscoveryFinished, signatureRequired and endOfTransaction. The corresponding removal method, removeRequiredEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter Notes
listener *
Required		 An implementation of the Events.Required interface


Returns

Boolean
true if the new listener was added successfully

Code example

//Register a listener for required events
this.api.addRequiredEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Required {

    void signatureRequired(SignatureRequest request, Device device);

    void endOfTransaction(TransactionResult result, Device device);

    void deviceDiscoveryFinished(List devices);
}

Add Status Notification Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



addStatusNotificationEventHandler

Adds a listener so transaction information can be retrieved. This listener fetches information from the following events : connectionStatusChanged, currentTransactionStatus. The corresponding removal method, removeStatusNotificationEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter Notes
listener *
Status		 An implementation of the Events.Status interface


Returns

Boolean
true if the new listener was added successfully

Code example

//Register a listener for transaction information events
this.api.addStatusNotificationEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Status {

    void connectionStatusChanged(ConnectionStatus status, Device device);

    void currentTransactionStatus(StatusInfo info, Device device);
}

Add Log Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



addLogEventHandler

Adds a listener so log information can be retrieved. This listener fetches information from the following events : onMessageLogged, deviceLogsReady. The corresponding removal method, removeLogEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter Notes
listener *
Log		 An implementation of the Events.Log interface


Returns

Boolean
true if the new listener was added successfully

Code example

//Register a listener for log information events
this.api.addLogEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.Log {

    void deviceLogsReady(String logs, Device device);

    void onMessageLogged(LogLevel level, String message);
}

Add Pending Results Event Handler

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



addPendingResultsEventHandler

Adds a listener so information can be retrieved when there is a pending TransactionResult. This listener fetches information from the following events : pendingTransactionResult, transactionResultReady. The corresponding removal method, removePendingResultsEventHandler, must be called before the end of your applications life-time to prevent memory leakage.

Parameters

Parameter Notes
listener *
PendingResults		 An implementation of the Events.PendingResult interface


Returns

Boolean
true if the new listener was added successfully

Code example

//Register a listener for log information events
this.api.addPendingResultsEventHandler(this);
//In this context the keyword "this" is an implementation of:
interface Events.PendingResults {

    void pendingTransactionResult(Device device);

    void transactionResultReady(TransactionResult transactionResult, Device device);
}

Remove Required Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



removeRequiredEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter Notes
listener *
Required		 The listener to be removed


Returns

Boolean
true if the listener was removed successfully

Code example

//Remove a listener for required events
this.api.removeRequiredEventHandler(this);

Remove Status Notification Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



removeStatusNotificationEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter Notes
listener *
Status		 The listener to be removed


Returns

Boolean
true if the listener was removed successfully

Code example

//Remove a listener for status notification events
this.api.removeStatusNotificationEventHandler(this);

Remove Log Event Handler

method Available since 3.1.1 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



removeLogEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter Notes
listener *
Log		 The listener to be removed


Returns

Boolean
true if the listener was removed successfully

Code example

//Remove a listener for log events
this.api.removeLogEventHandler(this);

Remove Pending Results Event Handler

method Available since 3.2.5 Deprecated since 5.0.0

Warning!

This method has been marked as deprecated. We strongly discourage you to use it.



removePendingResultsEventHandler

Removes a listener so information is not passed on to that listener any more.

Parameters

Parameter Notes
listener *
PendingResults		 The listener to be removed


Returns

Boolean
true if the listener was removed successfully

Code example

//Remove a listener for pending results events
this.api.removePendingResultsEventHandler(this);

Objects

Transaction Result

object Available since 4.2.1

TransactionResult

An object holding information about a transaction result.

Properties

Property Description
StatusMessage
String		 Gets the status message from the TransactionResult. The status message is a human readable string from our servers which contains a value representing the result from the server side. "AUTH CODE 12345" for example.
Type
TransactionType		 Gets the transaction type from the TransactionResult. The transaction type represents which type of transaction was done. "SALE" for example.
FinStatus
FinancialStatus		 Gets the financial status from the TransactionResult. The financial status describes the conclusion of the transaction as received from the card reader. "AUTHORISED" for example.
RequestedAmount
BigInteger		 Gets the requested amount from the TransactionResult. The requested amount is the payment amount sent in the original request to the card reader, i.e. the amount which was to charge the card with.
GratuityAmount
BigInteger		 Gets the gratuity amount from the TransactionResult. The gratuity amount is an additional amount added to the requested payment amount which represents additional fee added to the requested amount. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. The customer inputs an additional amount as a tip, lets say 100. The card is then charged for the requested amount, 1000, as well as the additional gratuity amount, 100. The result will be that the card will be charged for 1100. A calculated gratuity percentage will also be returned.
GratuityPercentage
double		 Gets the gratuity percentage from the TransactionResult The gratuity percentage is used to calculate an additional amount to the requested amount. The card reader calculates that amount, rounded up to the closest whole number. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. Instead of the customer adding a value he selects the percentage of the requested amount to be applied as a tip, lets say 10%. The card is then charged for the requested amount, 1000, as well as the additional gratuity percentage, 10%. The result will be that the card will be charged for 1100. A calculated gratuity amount will also be returned.
TotalAmount
BigInteger		 Gets the total amount from the TransactionResult. The total amount is the amount the card was charged for. It is possible that the total amount is not the same as the requested amount since an additional fee can be added, with the customer's approval, via the tipping functionality.
Currency
Currency		 Gets the currency from the TransactionResult. The currency used in this transaction.
TransactionID
String		 Gets the device transaction id from the TransactionResult. The transaction id is an internal increasing counter in the card reader which is incremented in each transaction.
eFTTransactionID
String		 Gets the device transaction id from the TransactionResult. The EFT (electronic funds transfer) transaction id is a unique GUID from the servers which is linked to this transaction in order to search for a particual transaction. This id is used if a transaction is to be reversed.
OriginalEFTTransactionID
String		 Gets the original EFT transaction id from the TransactionResult. The original EFT (electronic funds transfer) transaction id is a unique GUID previously received from the servers in order to reverse a transaction. This id is sent with the new eFTTransactionID in order to reference the original transaction. An example: A transaction is made. An eFTTransactionID is received. That transaction has to be reversed. A new transaction is started, now a reverse transaction, with the previously received eFTTransactionID as a parameter in the transaction. In the end result there will be a new eFTTransactionID, for the reverse transaction, and an originalEFTTransactionID referencing the original transaction.
eFTTimestamp
Date		 Gets the time stamp from the TransactionResult. The eFTTimestamp represents the time when the transaction was done. This time is set by the device communicating to the card reader when the connection is established to the card reader.
AuthorisationCode
String		 Gets the authorisation code from the TransactionResult. If the transaction was authorised the value represented can be used to search for a transaction in our system.
VerificationMethod
VerificationMethod		 Gets the verification method from the TransactionResult. The verification method represents the card holder verification method used to allow the payment. "PIN" for example.
CardEntryType
CardEntryType		 Gets the card entry type from the TransactionResult. The card entry type is the method the card information was input to card reader. "ICC" for example represents "Integrated Circuit Card" i.e. the information was read from the chip of the card.
CardSchemeName
String		 Gets the card scheme name from the TransactionResult. The scheme which was used when the transaction was made.
ErrorMessage
String		 Gets the error message from the TransactionResult. If there was an error during the transaction it is represented here in a human readable text.
CustomerReference
String		 Gets the customer reference from the TransactionResult. If a customer reference was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The customer reference can be used to reference in internal systems.
BudgetNumber
String		 Gets the budget number from the TransactionResult. If a budget number was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The budget number can be used to split payments over a period of months.
RecoveredTransaction
boolean		 Gets the flag recovered transaction from the TransactionResult. 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.
CardTypeId
String		 Gets the card type id from the transaction. The card type id is an identifier inside the Handpoint gateway which represents what kind of card was used. "U015" for example represents SAS Airline-Systems in our systems.
MerchantReceipt
String		 Gets the merchant receipt from the TransactionResult. An HTML containing the merchant receipt.
CustomerReceipt
String		 Gets the customer receipt from the TransactionResult. An HTML containing the customer receipt.
DeviceStatus
DeviceStatus		 Gets the device status from the TransactionResult.
CardToken
String		 Gets the card token if it's available, null otherwise.

Card Entry Type

enum Available since 3.0.0

CardEntryType

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

Connection Method

enum Available since 3.2.1

ConnectionMethod

An enum representing different types of connection methods.

Currently BLUETOOTH and SIMULATOR are supported for android devices.

Possible values

USB SERIAL BLUETOOTH HTTPS WIFI ETHERNET SIMULATOR

Code example

//Currently BLUETOOTH and SIMULATOR are the only ConnectionMethod available.
public enum ConnectionMethod {
	USB,
	SERIAL,
	BLUETOOTH,
	HTTPS,
	WIFI,
	ETHERNET,
	SIMULATOR
}

Connection Status

enum Available since 3.5.5

ConnectionStatus

A list of statuses given to a connection

Possible values

Connected Connecting Disconnected Disconnecting Initializing NotConfigured

Currency

enum Available since 3.0.0

Currency

An enum of currencies.

It contains the name of the currency, its ISO code, as well as 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

Balance Sign

String Available since 1.0.0

BalanceSign

An enum representing the balance sign

Possible values

POSITIVE_SIGN('C') NEGATIVE_SIGN('D')

Device

object Available since 3.0.0

Device

An object to store the information about the device we're working with.

Methods

Constructor

Device( String name , String address , String port , ConnectionMethod connectionMethod , String sharedSecret , int timeout );

Parameter Notes
name *
String		 A name to identify the device
address *
String		 The address of the device you wish to connect to. E.g.: "08:00:69:02:01:FC" for bluetooth or "192.168.1.105" for ethernet.
port *
String		 The port to connect to.
connectionMethod *
ConnectionMethod		 Enumerated type to specify the type of connection with the device. E.g: Bluetooth, Cloud, Serial, etc...
sharedSecret
String		 This is used if you want this specific device to use the specified sharedSecret instead of the default one proviced in the initialization.
timeout
int		 The amount of miliseconds to consider the connection has timed out. If not set, the default timeout is 15 seconds.

Properties

Property Description
Id
String		 An unique identifier of the device.

Code example

//Create and init a new Device
Device dev = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH);

Balance

object Available since 1.0.0

Balance

Balance available on the card

Properties

Property Description
amount
Integer		 The amount balance
currency
Curreny		 The balance currency
sign
BalanceSign		 Positive (C) or negative (D) balance. You can retrieve the balance sign using the methods isPositive() or isNegative()

Code example

Balance balance = Balance.Companion.factory(
    "1000", 
    Currency.EUR.getAlpha(), 
    BalanceSign.POSITIVE_SIGN.name()
  )

Device Parameter

enum Available since 3.0.0

DeviceParameter

An enum describing all the admin commands to send to a payment terminal.

Possible values

BluetoothName BluetoothPass SystemTimeout ScreenTimeout SignatureTimeout

Device Status

object Available since 3.2.1

DeviceStatus

A class which holds the status of the payment terminal.

Properties

Property Description
SerialNumber
String		 Gets the serial number of the payment terminal
BatteryStatus
String		 Gets the battery status of the payment terminal (in percentages)
BatterymV
String		 Gets the battery voltage of the payment terminal
BatteryCharging
String		 Gets the battery charging status of the payment terminal
ExternalPower
String		 Gets the status of the payment terminal external power
ApplicationName
String		 Gets the application name of the payment terminal
ApplicationVersion
String		 Gets the application version of the payment terminal

Financial Status

enum Available since 4.0.1

FinancialStatus

An enum representing different statuses of a finalized transaction

Possible values

UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED PARTIAL_APPROVAL

Hapi Manager

object Available since 3.2.5

HapiManager

A static class containing information about the current status of the SDK

Properties

Property Description
DefaultSharedSecret
String		 Gets the default shared secret in use.
LogLevel
LogLevel		 Gets the current log level of the SDK and payment terminal.
inTransaction
boolean		 Checks whether the SDK is in the middle of a transaction. True if the SDK is in a transaction, false otherwise.
SdkVersion
String		 Gets the current SDK version.
isTransactionResultPending
boolean		 In the case of a communication failure between the payment terminal and the SDK a TransactionResult might have not been delivered. This function checks if there is a pending TransactionResult. This field is only updated when connecting to a payment terminal. If this function returns true the TransactionResult (which includes the receipt) can be fetched.getPendingTransactionResult();. This function serves the same functionality as the event pendingTransactionResult(Device device), so every time this event is invoked, HapiManager.IsTransactionResultPending() is true until the result is fetched.
Settings.AutomaticReconnection
boolean		 When this property is set to true, the SDK will automatically try to reconnect to the payment terminal after a disconnection. The SDK internally maintains a reconnection thread which keeps on trying to connect until it succeeds. The delay between reconnections is exponentially increased on every new attempt. The default value for this property is true

Code example

//Check if the SDK is in transaction
boolean inTransaction = HapiManager.inTransaction(someConnectedDevice);
//Check the current logLevel
LogLevel level = HapiManager.getLogLevel();

//Disable automatic reconnection feature
HapiManager.Settings.AutomaticReconnection = false;

Handpoint API (Hapi) factory

object Available since 3.0.0

HapiFactory

A factory to provide a unified entrypoint and to simplify the way to instantiate the Hapi object.

Methods

Static factory

getAsyncInterface( Events.Required requiredListener , Context context );

Parameter Notes
requiredListener *
Events.Required		 A listener object to report the required events.
context *
Context		 The Android context in order to handle bluetooth.

Code example

//An Android Context is required to be able to handle bluetooth
public void initApi(Context context) {
	String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
	this.api = HapiFactory.getAsyncInterface(this, context).defaultSharedSecret(sharedSecret);
}

Log Level

enum Available since 3.0.0

LogLevel

An enum describing the different levels of logging available.

Possible values

None Info Full Debug

Optional Transaction Parameters

object Available since 3.0.0

OptionalParameters

A class containing optional transaction parameters supported by the payment terminal.

Properties

Property Description
Budget
String		 Budget is only available for sale transactions.
 A String representing the key for a budget number.

A budget number can be used to split up an amout over a period of months. The value has to be a String of 2 digits representing the number of months to split the transaction to.
CustomerReference
String		 CustomerReference is available for all transactions.
A String representing the key for a customer reference.

A customer reference can be used for an internal marking system. The value is sent as a String of a maximum 25 characters and received back when the transaction has been processed.

Status

enum Available since 3.1.1

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

Status Info

object Available since 3.5.5

statusInfo

A class containing information about the status of the transaction.

Properties

Property Description
cancelAllowed
bool		 A boolean letting the integrator know if the terminal will accept a stop transaction request.
status
Status		 A Status enum representing the status of the transaction.
message
String		 A String containing the status message of the transaction.
deviceStatus
DeviceStatus		 A DeviceStatus object containing information about the payment terminal.

Signature Request

object Available since 3.2.1

SignatureRequest

A class containing information about a signature verification.

Properties

Property Description
Timeout
int		 int the value of the timeout in seconds.
MerchantReceipt
String		 String the merchant receipt as html.

Transaction Type

enum Available since 3.0.0

TransactionType

An enum representing different types of transactions.

Possible values

UNDEFINED SALE VOID_SALE REFUND VOID_REFUND REVERSAL CANCEL_SALE CANCEL_REFUND TOKENIZE_CARD SALE_AND_TOKENIZE_CARD

Verification Method

enum Available since 3.0.0

VerificationMethod

An enum representing different verification methods used in the transaction.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED