Version: Next

Objects

Transaction Result

TransactionResult Object

An object holding information about the result of a transaction.

tip

signatureUrl: In case the signature can not be updated to the Handpoint servers and an URL is not generated, the terminal will send back the image binary in base64 format to your software. It is important to be able to support both the URL and the image binary format.

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

Properties

Parameter	Description
`aid` String	Application Identifier of the card (EMV tag 9F06).
`arc` String	EMV Authorisation Response Code (EMV tag 8A).
`authorisationCode` String	Acquirer response code.
`balance` Balance	Balance available on the card.
`budgetNumber` String	Used to split payments over a period of months.
`cardEntryType` CardEntryType	Method used by the terminal to read the card.
`cardLanguagePreference` String	Preferred language of the card (EMV tag 5F2D).
`cardSchemeName` CardSchemeName	The brand of the card.
`cardToken` String	Token representing the PAN of the card.
`chipTransactionReport` String	Full report of the card EMV parameters.
`currency` Currency	The currency used for the transaction.
`customerReceipt` String	A URL containing the customer receipt in HTML format. 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.
`customerReference` String	If a customerReference was provided as an optional parameter in the transaction request it is echoed unaltered in this field.
`deviceStatus` DeviceStatus	Status of the device.
`dueAmount` String	In case of a partial approval for the transaction, this field contains the amount which remains to be paid.
`efttimestamp` Date	Time of the transaction.
`efttransactionID` String	Handpoint unique identifier for a transaction, this id is the one to be used for a transaction to be reversed.
`errorMessage` String	Detailed reason for the transaction error.
`expiryDateMMYY` String	Expiry date of the card used for the operation.
`finStatus` FinancialStatus	The financial status contains the outcome of the transaction. For example "AUTHORISED" or "DECLINED".
`iad` String	Issuer Application Data (EMV tag 9F10).
`issuerResponseCode` String	Response code from the card issuer.
`maskedCardNumber` String	Masked card number of the card used for the operation.
`merchantAddress` String	Merchant Address.
`merchantName` String	Merchant Name.
`merchantReceipt` String	A URL containing the customer receipt in HTML format. 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.
`metadata` Metadata	If metadata was provided as an optional parameter in the transaction request it is echoed unaltered in this field
`mid` String	Merchant Identifier.
`originalEFTTransactionID` String	In case the transaction type is a reversal, this field will contain the identifier of the original transaction being reversed.
`paymentScenario` PaymentScenario	Indicates the card entry mode.
`recoveredTransaction` Boolean	This flag is set to true if the transaction result is sent through the transaction recovery logic (network or communication failure), false otherwise.
`requestedAmount` BigInteger	The requested amount is the transaction amount sent to the terminal.
`rrn` String	Retrieval Reference Number, unique number assigned by the acquirer.
`signatureUrl` String	If a digital signature is required, this is the URL containing the image of the captured signature. In case the signature can not be updated to the Handpoint servers and an URL is not generated, the terminal will send back the image binary in base64 format to your software. It is important to be able to support both the URL and the image binary format.
`statusMessage` String	The status of the transaction, for example "Waiting for pin".
`tenderType` TenderType	Transaction tender type (credit / debit).
`tid` String	Terminal Identifier.
`tipAmount` BigInteger	Tip amount, if any, in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`tipPercentage` Double	If tipping is enabled, this field will return the tip percentage added on top of the base amount.
`totalAmount` BigInteger	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.
`transactionID` String	The transaction id is a terminal internal counter incremented for each transaction.
`tsi` String	Transaction Status Information (EMV tag 9B).
`tvr` String	Transaction Verification Results (EMV tag 95).
`type` TransactionType	The type of transaction initiated, for example "SALE".
`unMaskedPan` String	Unmasked PAN, only received if the card is a non-payment card (loyalty).
`verificationMethod` VerificationMethod	cardholder verification method, for example "PIN".
`multiLanguageStatusMessages` Map	`Map` containing the status message in a human readable format for all the supported locales.
`multiLanguageErrorMessages` Map	`Map` containing the error message in a human readable format for all the supported locales.
`cardHolderName` String	Name of the cardholder.

Code example

{
  "aid": "A0000000041010",
  "arc": "0000",
  "authorisationCode": "123456",
  "balance": null,
  "budgetNumber": "",
  "cardEntryType": "UNDEFINED",
  "cardLanguagePreference": "",
  "cardSchemeName": "MasterCard",
  "cardToken": "",
  "chipTransactionReport": "",
  "currency": "USD",
  "customerReceipt": "https://s3.[...]/customerReceipt.html",
  "customerReference": "",
  "deviceStatus": {
      "applicationName": "ClientApp",
      "applicationVersion": "20.1.0",
      "batteryCharging": "Not Charging",
      "batteryStatus": "100",
      "batterymV": "4126",
      "bluetoothName": "PAXA920",
      "externalPower": "USB",
      "serialNumber": "0821032398",
      "statusMessage": "Approved or completed successfully"
  },
  "dueAmount": 0,
  "errorMessage": "",
  "expiryDateMMYY": "0422",
  "finStatus": "AUTHORISED",
  "iad": "0210A000002A0000000000000000000000FF",
  "issuerResponseCode": "00",
  "maskedCardNumber": "************1456",
  "merchantAddress": "Plaza Soledad Torres Acosta 1 28013 Madrid",
  "merchantName": "Hago la cama",
  "merchantReceipt": "https://s3.[...]/merchantReceipt.html",
  "metadata": {
    "metadata1":"data 1",
    "metadata2":"data 2",
    "metadata3":"data 3",
    "metadata4":"data 4",
    "metadata5":"data 5",
  },
  "mid": "",
  "originalEFTTransactionID": "",
  "paymentScenario": "CHIPCONTACTLESS",
  "rrn": "",
  "signatureUrl": "",
  "statusMessage": "Approved or completed successfully",
  "tenderType": "CREDIT",
  "tid": "ACQUIRER_TID",
  "tipAmount": 0,
  "totalAmount": 100,
  "transactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "tsi": "0000",
  "tvr": "0400008001",
  "type": "SALE",
  "unMaskedPan": "",
  "verificationMethod": "UNDEFINED",
  "efttimestamp": 1615374961000,
  "efttransactionID": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "requestedAmount": 100,
  "tipPercentage": 0,
  "recoveredTransaction": false,
  "multiLanguageStatusMessages": [
        { "en_US" : "Approved or completed successfully" },
        { "fr_FR" : "Transaction approuvée" }
  ],
  "multiLanguageErrorMessages": [],
  "cardHolderName": "cardholder name"
}

Acquirer

Acquirer Enum

An enum representing all the supported acquirers for merchant authentication.

Possible values

AMEX BORGUN EVO OMNIPAY POSTBRIDGE INTERAC TSYS VANTIV SANDBOX

Code example

public enum Acquirer {  AMEX,
    BORGUN,
    EVO,
    OMNIPAY,
    POSTBRIDGE,
    INTERAC,
    TSYS,
    VANTIV,
    SANDBOX
}

Balance

Balance Object

Balance available on the card

Properties

Parameter	Description
`amount` Integer	The amount balance
`currency` Currency	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()
  )

Balance Sign

BalanceSign Enum

An enum representing the balance sign.

Possible values

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

Card Brands

CardBrands Enum

A string representing the supported card brands.

Possible values

VISA MASTERCARD MAESTRO AMEX DISCOVER DINERS JCB INTERAC OTHER

Card Entry Type

CardEntryType Enum

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

Card Scheme Name

CardSchemeName Enum

A string representing different card brands.

Possible values

MasterCard Visa Maestro American Express Discover JCB Diners UnionPay Interac

Card Tokenization Data

CardTokenizationData Object

An object representing the tokenized card.

Properties

Parameter	Description
`token` String	Token representing the card number
`expiryDate` String	Expiration date of the card
`tenderType` TenderType	ternder type of the card (credit/debit)
`issuerCountryCode` CountryCode	The country code of the issuer of the card (ISO 3166-1)

Connection Method

ConnectionMethod Enum

An enum representing different connection methods with the payment terminal.

Currently BLUETOOTH, ANDROID_PAYMENT and USB are the only supported types.

Possible values

BLUETOOTH ANDROID_PAYMENT USB

Code example

//Currently BLUETOOTH, ANDROID_PAYMENT and USB are the only connection methods available.
public enum ConnectionMethod {
  BLUETOOTH,
  ANDROID_PAYMENT,
  USB
}

Connection Status

ConnectionStatus Enum

A list of connection statuses. Note: the events starting with Cloud[...] are exclusively for devices linked to merchants with CLOUD Api key (CLOUD mode enabled) and can be safely ignored for Android native integrations.

Possible values

Connected Connecting Disconnected Disconnecting NotConfigured Initializing CloudConnected CloudInitialized CloudAvailable CloudDisconnected CloudUnavailable

Currency

Currency Enum

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

Device

Device Object

An object to store the information about the payment terminal in use.

Methods

Constructor

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

Parameter	Notes
`name` Required String	A name to identify the device
`address` Required String	The address of the device you wish to connect to. E.g.: "08:00:69:02:01:FC" for bluetooth or just an identifier if your application is running directly on a PAX or Telpo device (ConnectionMethod.ANDROID_PAYMENT).
`usbDevice` Required UsbDevice	Represents a concrete attached USB device.
`connectionMethod` Required ConnectionMethod	Type of connection with the payment terminal. E.g: Bluetooth
`sharedSecret` String	Replaces the default shared secret proviced in the initialization step.
`timeout` int	The number of miliseconds until a connection is considered timed out. If not set, the default timeout is 15 seconds.

Properties

Parameter	Description
`Id ` String*	A unique identifier for the payment terminal.

Code example

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

//Create and init a new PAX/Telpo Device for a ANDROID_PAYMENT connection
Device dev = new Device("LocalPaxOrTelpo", "LocalHost", "null", ConnectionMethod.ANDROID_PAYMENT);

Device Capabilities

DeviceCapabilities Object

An object holding the capabilities of the payment terminal.

Properties

Parameter	Description
`printer` Boolean	True if the terminal has printer, false otherwise
`cloudApi` Boolean	True if the terminal is cloud-enabled, false otherwise

Device Parameter

DeviceParameter Enum

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

Possible values

BluetoothName BluetoothPass SystemTimeout ScreenTimeout SignatureTimeout

Device Status

DeviceStatus Object

A class which holds the status of the payment terminal.

Properties

Parameter	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

FinancialStatus Enum

An enum representing different statuses of a finalized transaction

Possible values

UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED PARTIAL_APPROVAL IN_PROGRESS REFUNDED CAPTURED

Description of the different financial statuses:

Parameter	Notes
`UNDEFINED` (NOT FOUND)	Any financial status other than the below mentioned financial statuses will be `UNDEFINED`. The `UNDEFINED` (NOT FOUND) status can be returned as a response to the get transaction status method. This status means that the transaction does not exist in the Handpoint gateway. If this status is returned within 90s of the start of a transaction, there could be a chance that the cardholder has not inserted, swiped or tapped his card yet on the terminal and the Handpoint gateway might soon receive the transaction. If the `UNDEFINED` status is returned after 90s, it means that the transaction processed has not reached the Handpoint gateway and it will NOT be charged.
`AUTHORISED`	The transaction (Sale, Refund, etc.) has been authorised. Consider this value as "successful".
`DECLINED`	The transaction has been declined by the acquirer or issuer.
`PROCESSED`	The `printReceipt` operation was successful.
`FAILED`	Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to `FAILED`. This means the operation was unsuccessful and the transaction has not been charged.
`CANCELLED`	The transaction has been cancelled. For example if the `stopCurrentTransaction` operation has been used or the cancel button on the terminal has been pressed.
`PARTIAL_APPROVAL`	A partial approval is returned by the acquirer when funds have been partially authorized, for example if the cardholder does not have all the funds to cover the entire cost of the goods or services they are buying. The merchant can obtain the remainder of the purchase amount in another form of payment (cash, check or another card transaction for the remaining). `PARTIAL_APPROVAL` is only applicable to the United States market.
`IN_PROGRESS` *	The `IN_PROGRESS` status can be returned as a response to the get transaction status method. The transaction is known by the gateway but the result is not available yet. Please check the status again after a few seconds.
`REFUNDED` *	The `REFUNDED` status can be returned as a response to the get transaction status method. The original transaction (sale) has been refunded.
`CAPTURED`	The pre-authorization has been captured and funds are being moved to the merchant account. The `CAPTURED` financial status will only be returned in case a preAuthorizationCapture message was used to complete a pre-authorization. Regular Sales do NOT need to be captured and will not return a `CAPTURED` financial status.

* Financial statuses marked with an asterisk (*) can only be returned as a response to the get transaction status method.

Handpoint Credentials

HandpointCredentials Object

A class containing the credentials used to communicate with the payment terminal, essentially the shared secret (always required). Properties

Parameter	Description
`sharedSecret` String	`String` the value of the Shared secret.

Code example

{
    String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
    HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret);
    //We've even set a default shared secret!
}

Handpoint API (Hapi) Factory

HapiFactory Object

A factory to provide a unified entrypoint and simplify the instantiation of the Hapi object.

Methods

Static factory getAsyncInterface( Events.Required requiredListener , Context context , HandpointCredentials handpointCredentials );

Parameter	Notes
`requiredListener` Required Events.Required	A listener object to report the required events.
`context` Required Context	The Android context.
`handpointCredentials` Required HandpointCredentials	An object containing the actor's shared secret key.

Code example

//InitApi for Datecs devices or PAX/Telpo ConnectionMethod.ANDROID_PAYMENT
public void InitApi()
{
    String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
    api = HapiFactory.getAsyncInterface(this, new HandpointCredentials(sharedSecret));
    //The api is now initialized. Yay! we've even set a default shared secret
}

Hapi Manager

HapiManager Object

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

Properties

Parameter	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;

Log Level

LogLevel Enum

An enum describing the different levels of logging available.

Possible values

None Info Full Debug

Manufacturer

Manufacturer Enum

A string representing different payment terminal supported manufacturers.

Possible values

INVALID DATECS PAX TELPO

MerchantAuth

MerchantAuth Object

An object to store merchant authentication.

Methods

Constructor
MerchantAuth( );

Constructor
MerchantAuth( Credential credential );

Parameter	Description
`credential` Credential	If present, adds the given credential to the list.

Constructor
MerchantAuth( List<Credential> credentials );

Parameter	Description
`credential` List<Credential>	If present, the list of credentials.

Add Credential
add( Credential credential );

Parameter	Description
`credential` Required Credential	The credential to be added.

Code example

MerchantAuth auth = new MerchantAuth();
Credential credential = new Credential();
//Optionally
credential.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential.setMid(mid);
//Optionally
credential.setTid(tid);
//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). 
auth.add(credential);

Merchant Auth Credential

Credential Object

An object to store credentials (Acquirer, Mid, Tid, MCC and ExternalId) for merchant authentication.

Properties

Parameter	Description
`acquirer` Acquirer	If present, it links this credential to the specified acquirer. Required if more than one credential is provided.
`mid` String	For this transaction, overrides the default MID (merchant ID) saved in the terminal configuration.
`tid` String	For this transaction, overrides the default TID (terminal ID) saved in the terminal configuration.
`mcc` String	Merchant Category Code, overrides the default MCC saved in the terminal configuration.
`ExternalId` String	For this transaction, the External Id will be used to lookup the credential of the merchant in the Handpoint backend and process the transaction accordingly. The External id replaces the need to pass MID/TID/MCC as credentials

Code example

// Credential using Acquirer, MID, TID and  MCC
Credential credential1 = new Credential();
//Optionally
credential1.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential1.setMid(mid);
//Optionally
credential1.setTid(tid);
//Optionally
credential1.setMcc(mcc);

// Credential using ExternalId
Credential credential2 = new Credential();
credential2.setExternalId(externalId);

Merchant Auth Options

MerchantAuthOptions Object

An object to store merchant authentication options for regular operations.

Properties

Parameter	Description
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`MerchantAuth` MerchantAuth	An object containing all the credentials used to optionally authenticate a merchant

Code example

MerchantAuthOptions options = new MerchantAuthOptions();

//If you use a customer reference
options.setCustomerReference("Your customer reference");

//If you need Multi MID / Custom merchant Authentication
MerchantAuth auth = new MerchantAuth();
Credential credential = new Credential();
//Optionally
credential.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential.setMid(mid);
//Optionally
credential.setTid(tid);
//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). 
auth.add(credential);
options.setMerchantAuth(auth);

Metadata

Metadata Object

An object to store metadata. This field can be used to pass custom data to the Handpoint gateway, it will be echoed back in the transaction result. This field will also be part of the transaction response if querying the Handpoint transaction reporting API.

Properties

Property	Description
`metadata1` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata2` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata3` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata4` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`metadata5` String	An arbitrary string containing any information/data. Max length 250 characters Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`

Code example

// Option 1
Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5");

// Option 2
Metadata metadata = new Metadata();
metadata.setMetadata1("Data 1");
metadata.setMetadata2("Data 2");
metadata.setMetadata3("Data 3");
metadata.setMetadata4("Data 4");
metadata.setMetadata5("Data 5");

Money Remittance Options

MoneyRemittanceOptions Object

An object representing options for Mastercard money remittance transactions. The recipient's first and last name and the recipient's country code are mandatory for Mastercard transactions processed by merchants with category codes 4829 and 6540. VISA transactions do not require money remittance options to be sent.

Properties

Parameter	Description
`fullName` Required String	first and last name of the recipient of the funds
`countryCode` Required CountryCode	Country code of the recipient of the funds (ISO 3166-1 alpha-3)

Code example

MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA);

MoTo Channel

MoToChannel Enum

A enum representing the channel used for the card not present transaction (MO = Mail Order / TO = Telephone Order) .

Possible values

MO TO

MoTo Options

MoToOptions Object

An object to store optional parameters for card not present (MoTo) transactions.

Properties

Parameter	Description
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`Channel` MoToChannel	MO for Mail order - TO for Telephone order
`Tokenize` Boolean	Flag to activate tokenization of the operation, if this flag is set, a token representing the PAN of the card will be sent back by the Handpoint sytems
`MoneyRemittanceOptions` MoneyRemittanceOptions	An object representing options for Mastercard money remittance transactions.

Code example

MoToOptions options = new MoToOptions();
options.setCustomerReference("Trx3245");
options.setTokenize(true);
options.setTokenize(false);
options.setChannel(MoToChannel.MO);
options.setChannel(MoToChannel.TO);

//Adding Money Remitance options
MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA);
MoToOptions moToOptions = new MoToOptions(moneyRemittanceOptions);

Operation DTO

OperationDto Object

Object indicating which financial transaction type needs to be performed after tokenization of the card during a Tokenize and Modify operation.

Properties

Parameter	Description
`sale` Sale	A sale sends a payment request to the payment terminal.
`refund` Refund	A refund operation moves funds from the merchant account to the cardholder´s credit card.
`saleReversal` Sale Reversal	A sale reversal, also called sale VOID allows the user to reverse a previous sale operation.
`refundReversal` Refund Reversal	A refund reversal, also called refund VOID allows the merchant to reverse a previous refund operation.

Operation Start Result

OperationStartResult Object

Object containing information about the financial operation being performed.

Properties

Parameter	Description
`operationStarted` boolean	`true` if the operation has started. false otherwise
`transactionReference` String	The `transactionReference` must be saved on your end in case you do not get back the transaction result object at the end of the transaction. The `transactionReference` will allow you to query the Handpoint Gateway directly to know the outcome of the transaction in case it is not delivered as planned by the terminal at the end of the transaction. A linked refund or a reversal will not return a `transactionReference` because the transaction reference for those types of transactions is the same as the one received for the original financial operation.
`errorMessage` String	Detailed reason for the transaction error.

Optional Transaction Parameters

OptionalParameters Object

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

Properties

Parameter	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.

Options

options Object

An object to store customer reference options for regular operations.

Properties

Parameter	Description
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`Metadata` Metadata	Object used to store metadata, this data will be echoed in the transaction result. Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`

Code example

Options options = new Options();

//If you use a customer reference
options.setCustomerReference("Your customer reference");

// Metadata
Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5");
options.setMetadata(metadata);

Payment Scenario

PaymentScenario Enum

An enum representing different types of scenario.

Possible values

UNKNOWN MAGSTRIPE MAGSTRIPECONTACTLESS CHIP CHIPCONTACTLESS CHIPFAILMAGSTRIPE MOTO

PAX A80 Keys

PaxA80Keys String

A string representing the PAX A80 physical keyboard keys.

Possible values

0 1 2 3 4 5 6 7 8 9 GREEN ORANGE RED FUNC options
SaleOptions

Print Error

PrintError Enum

An enum representing different errors that can come from print action.

Possible values

Unexpected InvalidArgument CantConnectToPrinter NotSupported NoPermission PrinterDisabled NotWhitelisted Busy OutOfPaper DataPacketInvalid PrinterHasProblems PrinterOverheating PrintingUnfinished FontNotPresent FontFormatError TooLong BatteryTooLow PaperCutterError PaperCutterJam CoverOpen UnsupportedEncoding

Refund Options

RefundOptions Object

An object to store all the customization options for a refund.

Properties

Parameter	Description
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`MerchantAuth` MerchantAuth	An object containing all the credentials used to optionally authenticate a merchant
`PinBypass` Boolean	Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt. PIN Bypass should be set to True if you want to enable pin bypass for a transaction
`SignatureBypass` Boolean	Whether the terminal prompts for a signature, depends on how you configure this. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification. Signature Bypass should be set to True if you want to enable signature for this transaction
`CheckDuplicates` Boolean	Used to disable the duplicate payment check functionality. When a merchant is not 100% sure of the transaction outcome, they will reprocess the transaction leading to the cardholder being charged twice. In order to avoid this scenario, we are flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the second charge. This menu is pushed by the Handpoint SDK and will automatically be displayed on top of your own UI when required. The Handpoint SDK will only prompt the duplicate payment check menu in case the same card is used twice in a row to process a transaction for the same amount within a 5 minutes timeframe. The duplicate payment check feature is enabled by default but can be disabled by passing a false value.
`Metadata` Metadata	Object used to store metadata, this data will be echoed in the transaction result. Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`MoneyRemittanceOptions` MoneyRemittanceOptions	An object representing options for Mastercard money remittance transactions.

Code example

RefundOptions options = new RefundOptions();

//If you use a customer reference
options.setCustomerReference("Your customer reference");

//If you need Multi MID / Custom merchant Authentication
MerchantAuth auth = new MerchantAuth();
Credential credential = new Credential();
//Optionally
credential.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential.setMid(mid);
//Optionally
credential.setTid(tid);
//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). 
auth.add(credential);
options.setMerchantAuth(auth);

//If you need to enable pin bypass
options.setPinBypass(true);

//If you need to disable the duplicate payment check service
options.setCheckDuplicates(false);

// Metadata
Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5");
options.setMetadata(metadata);

//Adding Money Remitance options
MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA);
RefundOptions saleOptions = new RefundOptions(true, moneyRemittanceOptions);

Report Configuration

ReportConfiguration Object

An object to store all the configuration for a transactions report.

Properties

Parameter	Description
`currency` Currency	The currency to filter the transactions
`startDate` String	The start date in format 'YYYYMMDDHHmmss'.
`endDate` String	The end date in format 'YYYYMMDDHHmmss'.
`timeZone` String	The time zone in format '+00:00'.
`terminalSerialNumber` List	The serial number of the terminal to fetch the transactions from (if terminalSerialNumber is empty or null, the report will show all the transactions for this merchant).

Code example

ReportConfiguration configuration = new ReportConfiguration("'USD'", "'20210430000000'", "'20210430235959'", "null");

If you want to add terminal serial numbers: List terminalSerialNumber = new ArrayList<>();
terminalSerialNumber.add("0123456789");
terminalSerialNumber.add("9876543210");
 ... ;

Sale Options

SaleOptions Object

An object to store all the customization options for a sale.

Properties

Parameter	Description
`BudgetNumber` String	The budget number can be used to split payments over a period of months.
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`MerchantAuth` MerchantAuth	An object containing all the credentials used to optionally authenticate a merchant
`PinBypass` Boolean	Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt. PIN Bypass should be set to True if you want to enable pin bypass for a transaction
`SignatureBypass` Boolean	Whether the terminal prompts for a signature, depends on how you configure this. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification. Signature Bypass should be set to True if you want to enable signature for this transaction
`TipConfiguration` TipConfiguration	An object containing the tip configuration for this transaction
`CheckDuplicates` Boolean	Used to disable the duplicate payment check functionality. When a merchant is not 100% sure of the transaction outcome, they will reprocess the transaction leading to the cardholder being charged twice. In order to avoid this scenario, we are flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the second charge. This menu is pushed by the Handpoint SDK and will automatically be displayed on top of your own UI when required. The Handpoint SDK will only prompt the duplicate payment check menu in case the same card is used twice in a row to process a transaction for the same amount within a 5 minutes timeframe. The duplicate payment check feature is enabled by default but can be disabled by passing a false value.
`Metadata` Metadata	Object used to store metadata, this data will be echoed in the transaction result. Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`
`MoneyRemittanceOptions` MoneyRemittanceOptions	An object representing options for Mastercard money remittance transactions.

Code example

SaleOptions options = new SaleOptions();

//If you use a customer reference
options.setCustomerReference("Your customer reference");

//If you need Multi MID / Custom merchant Authentication
MerchantAuth auth = new MerchantAuth();
Credential credential = new Credential();
//Optionally
credential.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential.setMid(mid);
//Optionally
credential.setTid(tid);
//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). 
auth.add(credential);
options.setMerchantAuth(auth);

//If you need to enable pin bypass
options.setPinBypass(true);

//If you need to disable the duplicate payment check service
options.setCheckDuplicates(false);

//If you want to specify the budget period
//Only available for SureSwipe
options.setBudgetNumber(YOUR_BUDGET_NUMBER);

//If you want to specify tip options
//Only available for PAX and Telpo terminals.
TipConfiguration config = new TipConfiguration();
//Optionally
config.setHeaderName(HEADER);
//Optionally
config.setFooter(FOOTER);
//Optionally
config.setEnterAmountEnabled(true);
//Optionally
config.setSkipEnabled(true);
config.setTipPercentages(percentages);
options.setTipConfiguration(config);

//Alternatively, you can set the tip amount directly
options.setTipConfiguration(new TipConfiguration(AMOUNT));

// Metadata
Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5");
options.setMetadata(metadata);

//Adding Money Remitance options
MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA);
SaleOptions saleOptions = new SaleOptions(true,moneyRemittanceOptions);

Sale and Tokenize Options

SaleAndTokenizeOptions Object

An object to store all the customization options for a sale and tokenize options.

Parameter	Description
`BudgetNumber` String	The budget number can be used to split payments over a period of months.
`CustomerReference` String	An arbitrary string to use as your own identifier for a transaction
`MerchantAuth` MerchantAuth	An object containing all the credentials used to optionally authenticate a merchant
`PinBypass` Boolean	Bypasses PIN entry when the shopper says they don't know the PIN for the card and the merchant either knows they are the legitimate cardholder or want to give them the benefit of the doubt. PIN Bypass should be set to True if you want to enable pin bypass for a transaction
`SignatureBypass` Boolean	Whether the terminal prompts for a signature, depends on how you configure this. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature; they regard it as optional for card-present transactions. This means you can speed up your checkout by skipping the signature prompt. But if your business requires it, you can still let the terminal prompt for a signature. The shopper then provides their signature on the touch screen of the terminal or on the printed transaction receipt. This depends on how you configure this setting. It is your responsibility to verify the signature of the shopper with the signature on the card or another form of identification. Signature Bypass should be set to True if you want to enable signature for this transaction
`TipConfiguration` TipConfiguration	An object containing the tip configuration for this transaction
`CheckDuplicates` Boolean	Used to disable the duplicate payment check functionality. When a merchant is not 100% sure of the transaction outcome, they will reprocess the transaction leading to the cardholder being charged twice. In order to avoid this scenario, we are flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the second charge. This menu is pushed by the Handpoint SDK and will automatically be displayed on top of your own UI when required. The Handpoint SDK will only prompt the duplicate payment check menu in case the same card is used twice in a row to process a transaction for the same amount within a 5 minutes timeframe. The duplicate payment check feature is enabled by default but can be disabled by passing a false value.
`MoneyRemittanceOptions` MoneyRemittanceOptions	An object representing options for Mastercard money remittance transactions.

Code example

SaleAndTokenizeOptions options = new SaleAndTokenizeOptions();

//If you use a customer reference
options.setCustomerReference("Your customer reference");

//If you need Multi MID / Custom merchant Authentication
MerchantAuth auth = new MerchantAuth();
Credential credential = new Credential();
//Optionally
credential.setAcquirer(YOUR_ACQUIRER);
//Optionally
credential.setMid(mid);
//Optionally
credential.setTid(tid);
//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). 
auth.add(credential);
options.setMerchantAuth(auth);

//If you need to enable pin bypass
options.setPinBypass(true);

//If you need to disable the duplicate payment check service
options.setCheckDuplicates(false);

//If you want to specify the budget period
//Only available for SureSwipe
options.setBudgetNumber(YOUR_BUDGET_NUMBER);

//If you want to specify tip options
//Only available for PAX and Telpo terminals.
TipConfiguration config = new TipConfiguration();
//Optionally
config.setHeaderName(HEADER);
//Optionally
config.setFooter(FOOTER);
//Optionally
config.setEnterAmountEnabled(true);
//Optionally
config.setSkipEnabled(true);
config.setTipPercentages(percentages);
options.setTipConfiguration(config);

//Alternatively, you can set the tip amount directly
options.setTipConfiguration(new TipConfiguration(AMOUNT));

//Adding Money Remitance options
MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA);
SaleAndTokenizeOptions saleAndTokenizeOptions= new SaleAndTokenizeOptions(moneyRemittanceOptions);

Settings

Settings Object

An Object holding the SDK initialization settings

Properties

Parameter	Description
`automaticReconnection` boolean	When this property is set to true, the SDK will automatically try to reconnect to the terminal after disconnection. The SDK maintains internally 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 false
`autoRecoverTransactionResult` boolean	The default value for this property is false
`sendToDeviceMaxAttempts` Integer	Number of retry attemps when there is an error communicating with the card reader. The default value for this property is 3
`timeBetweenAttempts` Integer	Time in milliseconds between attempts. The default value for this property is 5000
`showSDKUIComponents` boolean	The default value for this property is false
`getReceiptsAsURLs` boolean	The default value for this property is false

Signature Request

SignatureRequest Object

A class containing information about a signature verification.

Properties

Parameter	Description
`timeout` int	`int` the value of the timeout in seconds.
`MerchantReceipt` String	`String` the merchant receipt as html. 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.

Status

status Enum

An enum containing information about the status of a transaction.

Possible values

Undefined Success InvalidData ProcessingError CommandNotAllowed NotInitialised ConnectTimeout ConnectError SendingError ReceivingError NoDataAvailable TransactionNotAllowed UnsupportedCurrency NoHostAvailable CardReaderError CardReadingFailed InvalidCard InputTimeout UserCancelled InvalidSignature WaitingForCard CardInserted ApplicationSelection ApplicationConfirmation AmountValidation PinInput ManualCardInput WaitingForCardRemoval TipInput SharedSecretInvalid SharedSecretAuth WaitingSignature WaitingHostConnect WaitingHostSend WaitingHostReceive WaitingHostDisconnect PinInputCompleted PosCancelled RequestInvalid CardCancelled CardBlocked RequestAuthTimeout RequestPaymentTimeout ResponseAuthTimeout ResponsePaymentTimeout IccCardSwiped RemoveCard ScannerIsNotSupported ScannerEvent BatteryTooLow AccountTypeSelection BtIsNotSupported PaymentCodeSelection PartialApproval AmountDueValidation InvalidUrl WaitingCustomerReceipt PrintingMerchantReceipt PrintingCustomerReceipt UpdateStarted UpdateFinished UpdateFailed UpdateProgress WaitingHostPostSend WaitingHostPostReceive Rebooting PrinterOutOfPaper ErrorConnectingToPrinter CardTapped ReceiptPrintSuccess InvalidPinLength OfflinePinAttempt OfflinePinLastAttempt ProcessingSignature CardRemoved TipEntered CardLanguagePreference AutomaticPrintingStarted CancelOperationNotAllowed UpdateSoftwareStarted UpdateSoftwareFinished UpdateSoftwareFailed UpdateSoftwareProgress InstallSoftwareStarted InstallSoftwareFinished InstallSoftwareFailed InstallSoftwareProgress UpdateConfigStarted UpdateConfigFinished UpdateConfigFailed UpdateConfigProgress InitialisationComplete

Status Info

statusInfo Object

A class containing information about the status of the transaction.

Properties

Parameter	Description
`isCancelAllowed` Boolean	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.
`cardLanguage` SupportedLocales	The card language preference in all supported locales.
`multiLanguageMessages` Map	`map` containing the status message in a human readable format in all the supported locales.
`message` String	A `String` containing the status message of the transaction.
`deviceStatus` DeviceStatus	A `DeviceStatus` object containing information about the payment terminal.

Supported Locales

SupportedLocales Enum

An enum of the SDK supported languages.

Possible values

en_CA en_UK en_US es_ES hr_HR is_IS fr_FR pt_PT it_IT no_NO de_DE sl_SL et_EE

Tender Type

TenderType Enum

An enum representing different tender types.

Possible values

NOT_SET CREDIT DEBIT

Tip Configuration

TipConfiguration Object

Constructor

TipConfiguration( String tipAmount );

Parameter	Notes
`tipAmount` String	If present, the amount of the tip to be used for the transaction.

Properties

Parameter	Description
`amount` BigInteger	Transaction amount in the minor unit of currency (f.ex. 1000 is 10.00 GBP).
`baseAmount` BigInteger	Base amount used to calculate the tip - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). If no base amount is defined, the transaction amount is used as base amount.
`headerName` String	Name of the tipping menu appearing on the terminal. Default: Tip
`tipPercentages` List<Integer>	List of percentages used to calculate the tip amount. REQUIRED
`enterAmountEnabled` Boolean	Flag used to enable the cardholder to manually enter the tip amount. Default: true
`skipEnabled` Boolean	Flag used to enable the cardholder to skip the tipping step. Default: true
`footer` String	Footer note which will appear on the tipping menu. Default: Empty string

Code example

{
    "amount": "2000",
    "baseAmount": "2000",
    "headerName": "",
    "tipPercentages": [5,10,15,20,25],
    "enterAmountEnabled": true,
    "skipEnabled": false,
    "footer": "Thank you!!! ;)"
}

Transaction Type

TransactionType Enum

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 CARD_PAN

Type of Result

TypeOfResult Enum

An enum representing different types of device reports.

Possible values

STATUS REPORT BLUETOOTHNAME EMVCONFIGURATION

Verification Method

VerificationMethod Enum

An enum representing different verification methods used in the transaction.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED MOBILE_PASS_CODE

Objects

Transaction Result​

Acquirer​

Balance​

Balance Sign​

Card Brands​

Card Entry Type​

Card Scheme Name​

Card Tokenization Data​

Connection Method​

Connection Status​

Currency​

Device​

Device Capabilities​

Device Parameter​

Device Status​

Financial Status​

Handpoint Credentials​

Handpoint API (Hapi) Factory​

Hapi Manager​

Log Level​

Manufacturer​

MerchantAuth​

Merchant Auth Credential​

Merchant Auth Options​

Metadata​

Money Remittance Options​

MoTo Channel​

MoTo Options​

Operation DTO​

Operation Start Result​

Optional Transaction Parameters​

Options​

Payment Scenario​

PAX A80 Keys​

Print Error​

Refund Options​

Report Configuration​

Sale Options​

Sale and Tokenize Options​

Settings​

Signature Request​

Status​

Status Info​

Supported Locales​

Tender Type​

Tip Configuration​

Transaction Type​

Type of Result​

Verification Method​

Transaction Result

Acquirer

Balance

Balance Sign

Card Brands

Card Entry Type

Card Scheme Name

Card Tokenization Data

Connection Method

Connection Status

Currency

Device

Device Capabilities

Device Parameter

Device Status

Financial Status

Handpoint Credentials

Handpoint API (Hapi) Factory

Hapi Manager

Log Level

Manufacturer

MerchantAuth

Merchant Auth Credential

Merchant Auth Options

Metadata

Money Remittance Options

MoTo Channel

MoTo Options

Operation DTO

Operation Start Result

Optional Transaction Parameters

Options

Payment Scenario

PAX A80 Keys

Print Error

Refund Options

Report Configuration

Sale Options

Sale and Tokenize Options

Settings

Signature Request

Status

Status Info

Supported Locales

Tender Type

Tip Configuration

Transaction Type

Type of Result

Verification Method