Skip to main content
Version: Android SDK 7.1005.0

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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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 and ANDROID_PAYMENT are the only supported types.

Possible values

BLUETOOTH ANDROID_PAYMENT

Code example

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

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 , String port , ConnectionMethod connectionMethod , String sharedSecret , int timeout );
ParameterNotes
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).
port Required
String
The port to connect to (optional).
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

ParameterDescription
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", "", ConnectionMethod.ANDROID_PAYMENT);

Device Capabilities

DeviceCapabilities Object

An object holding the capabilities of the payment terminal.

Properties

ParameterDescription
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

ParameterDescription
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:

ParameterNotes
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

ParameterDescription
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 );

ParameterNotes
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

ParameterDescription
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 );
ParameterDescription
credential
Credential
If present, adds the given credential to the list.
Constructor
MerchantAuth( List<Credential> credentials );
ParameterDescription
credential
List<Credential>
If present, the list of credentials.
Add Credential
add( Credential credential );
ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

PropertyDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
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 );

ParameterNotes
tipAmount
String
If present, the amount of the tip to be used for the transaction.

Properties

ParameterDescription
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