Version: JavaScript SDK 6.1.0

Objects

Transaction Result Object

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

Property	Description
`aid` String	EMV 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	The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats
`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 payment terminal
`dueAmount` Number	In case of a partial approval for the transaction, this field contains the amount which remains to be paid. Partial approval support is only required by the card brands in the United States
`efttimestamp` Date (Unix epoch)	Time of the transaction (based on the date and time of the payment terminal)
`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	EMV 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	The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats
`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 explained in the Recovey Section, 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	EMV Transaction Status Information (EMV tag 9B)
`tvr` String	EMV 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",
  "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,
  "cardHolderName": "cardholder name"
}

Balance

Balance Object

Balance available on the card.

Properties

Property	Description
`amount` Integer	The balance amount.
`currency` Currency	The balance currency.
`positive` Boolean	Marks if the balance is positive.
`negative` Boolean	Marks if the balance is negative.

Code example

"balance": {
    "amount": 1000,
    "currency": "EUR",
    "negative": false,
    "positive": true
  }

Bypass Options

BypassOptions Object

Configuration to enable/disable signature or pin bypass.

Properties

Property Description

pinBypass
Boolean Bypasses PIN entry when the cardholder does not know the PIN of 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 in order for the cardholder to be able to bypass the PIN by clicking once on the "validate(green)" button of the PIN screen on the payment terminal.

signatureBypass
Boolean Whether the terminal prompts for a signature, depends on how you configure this parameter. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature for US merchants, 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.

Property	Description
`pinBypass` Boolean	Bypasses PIN entry when the cardholder does not know the PIN of 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 in order for the cardholder to be able to bypass the PIN by clicking once on the "validate(green)" button of the PIN screen on the payment terminal.
`signatureBypass` Boolean	Whether the terminal prompts for a signature, depends on how you configure this parameter. The major card schemes (American Express, Diners, Discover, JCB, Mastercard, Visa, UnionPay) no longer require a signature for US merchants, 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.

Code example

{
   "bypassOptions": {
       "signatureBypass": true,
       "pinBypass": true
       }
}

Device

Device Object

An object to store information about the payment terminal in use. ALL values are REQUIRED.

Properties

Property	Description
`merchant_id_alpha` Required String	Merchant unique identifier associated with the payment terminal.
`serial_number` Required String	Payment terminal serial number.
`ssk` Required String	Device shared secret key to authenticate financial operations.
`terminal_type` Required String	Payment terminal type.
`device_name` Required String	Payment terminal name composed of two parts "serial_number - terminal_type"

Code example

{
       "merchant_id_alpha": "Test_Merchant",
       "serial_number": "614004878",
       "ssk": "74817EA5C63437ADE7AA3A5401",
       "terminal_type": "PAXA920",
       "device_name": "0821032395-PAXA920"
}

Acquirer

Acquirer Enum

An enum representing the supported acquirers for merchant authentication

AMEX BORGUN EVO OMNIPAY POSTBRIDGE INTERAC TSYS VANTIV SANDBOX

Transaction Status

TransactionStatus Object

A class which holds the payment terminal status. This object is received in the financial operation callback.

Properties

Property	Description
`deviceStatus` Device Status	OPTIONAL - The status of the payment terminal.
`isCancelAllowed` boolean	Defines if the transaction can be cancelled or not.
`message` String	Human readable status message.
`status` status	An enum containing information about the status of the transaction.

Options

Options Object

An object to store all the customisation options for an operation. This object can be empty if no options are required.

Properties

Property	Description
`customerReference` String	An arbitrary string to use as your own identifier for a transaction

Code example

{
    "customerReference": "MyCustomReference"    
}

Sale Options

SaleOptions Object

An object to store the customization options for a sale operation. This object can be empty if no options are required.

Properties

Property	Description
`customerReference` String	An arbitrary string to use as your own identifier for a transaction.
`TipConfiguration` TipConfiguration	Configuration for the tipping menu of the payment terminal.
`bypassOptions` BypassOptions	Configuration required to bypass the pin or signature verification methods.
`merchantAuth` MerchantAuth	Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).

Code example

{
    "customerReference": "MyCustomReference",
    "tipConfiguration": {
        "baseAmount": "100",
        "skipEnabled": true,
        "enterAmountEnabled": true,
        "tipPercentages": [
            1,
            2,
            3,
            5
        ]
    },
    "bypassOptions": {
        "signatureBypass": true,
        "pinBypass": true
    },
    "merchantAuth": [
        {
            "acquirer": "ACQUIRER",
            "mid": "11111",
            "tid": "22222",
            "mcc": "33333"
        }
    ],
}

Refund Options

RefundOptions Object

An object to store the customization options for a refund. This object can be empty if no options are required.

Code example

Properties

Property	Description
`customerReference` String	An arbitrary string to use as your own identifier for a transaction.
`bypassOptions` BypassOptions	Configuration required to bypass the pin or signature verification methods.
`merchantAuth` MerchantAuth	Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).

{
    "customerReference": "MyCustomReference",
    "tipConfiguration": {
        "baseAmount": "100",
        "skipEnabled": true,
        "enterAmountEnabled": true,
        "tipPercentages": [
            1,
            2,
            3,
            5
        ]
    },
    "bypassOptions": {
        "signatureBypass": true,
        "pinBypass": true
    },
    "merchantAuth": [
        {
            "acquirer": "ACQUIRER",
            "mid": "11111",
            "tid": "22222",
            "mcc": "33333"
        }
    ],
}

Merchant Auth Options

MerchantAuthOptions Object

An object to store merchant authentication options for regular operations.

Properties

Property	Description
`customerReference` String	An arbitrary string to use as your own identifier for a transaction.
`merchantAuth` MerchantAuth	Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).

Code example

{
    "customerReference": "MyCustomReference",
    "merchantAuth": [
        {
            "acquirer": "ACQUIRER",
            "mid": "11111",
            "tid": "22222",
            "mcc": "33333"
        }
    ],
}

Merchant Auth

MerchantAuth Object

An object used to store merchant authentication. This object can be empty, it allows a transaction to be funded to a specific merchant account other than the default one (linked to the API key). It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office.

Properties

Property	Description
`Credential` Credential[]	Array of credentials.

Code example

{
   "merchantAuth": [{
       "acquirer": "ACQ_DUMMY",
       "mid": "1111",
       "tid": "2222",
       "mcc": "3333",
       "externalId": "4444"
       }]
}

Merchant Auth Credential

Credential Object

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

Properties

Property	Description
`acquirer` Acquirer	If present, it links the credential to a specific acquirer. Only 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

{
    "acquirer": "ACQ_DUMMY",
    "mid": "1111",
    "tid": "2222",
    "mcc": "3333"
}

{
    "externalId": "4444"
}

Financial Status

FinancialStatus Enum

An enum representing different statuses for a completed transaction.

Possible values

UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED PARTIAL_APPROVAL

Description of the different financial statuses:

Parameter	Notes
`UNDEFINED`	Any Financial Status other than the below mentioned financial statuses will be `UNDEFINED`. UNDEFINED means that the SDK couldn't get a response from the Gateway. An automatic cancellation service will try to cancel the transaction in case it was approved.
`AUTHORISED`	The transaction (Sale, Refund,...) 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`.
`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 the ability to partially authorize a transaction if the cardholder does not have the funds to cover the entire cost on their card. The merchant can obtain the remainder of the purchase amount in another form of payment. `PARTIAL_APPROVAL` is only applicable to the United States market.

Device Status

DeviceStatus Object

A class which holds the payment terminal status.

Properties

Property	Description
`SerialNumber` String	The serial number of the payment terminal.
`BatteryStatus` String	The battery status in percentages of the payment terminal.
`BatterymV` String	The battery millivolts of the payment terminal.
`BatteryCharging` String	The battery charging status of the payment terminal.
`ExternalPower` String	The external power status of the payment terminal.
`ApplicationName` String	The application name used by the payment terminal.
`ApplicationVersion` String	The application version number used by the payment terminal.
`bluetoothName` String	The bluetooth interface name used by the payment terminal.
`statusMessage` String	Status message of the payment terminal.

Code example

{
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "0821032397",
    "statusMessage": "Card reader time out"
}

Currency

Currency Enum

An enum of currencies.

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

Card Entry Type

CardEntryType Enum

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

Card Scheme Name

CardSchemeName Enum

An enum representing different card brands.

Possible values

MasterCard Visa Maestro American Express Discover JCB Diners UnionPay Interac

Verification Method

VerificationMethod Enum

An enum representing different cardholder verification methods.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED MOBILE_PASS_CODE

Payment Scenario

PaymentScenario Enum

An enum representing different types of payment scenario.

Possible values

UNKNOWN MAGSTRIPE MAGSTRIPECONTACTLESS CHIP CHIPCONTACTLESS CHIPFAILMAGSTRIPE MOTO

Status Info

statusInfo Object

A class containing information about the status of the transaction.

Properties

Property	Description
`cancelAllowed` bool	A `boolean` allowing the user to know if the payment terminal will accept a cancel request.
`status` status	A `status` enum representing the status of the transaction.
`message` String	A `string` containing the status message of the transaction.
`deviceStatus` Device Status	A `DeviceStatus` object containing information about the payment terminal.

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

Tender Type

TenderType Enum

An enum representing different tender types.

Possible values

NOT_SET CREDIT DEBIT

Tip Configuration

TipConfiguration Object

An object holding information about the configuration of the tipping menu for the payment terminal. When a tipping configuration is sent to the payment terminal, the card reader will prompt the cardholder with a tipping menu at the time of the transaction with the parameters that have been sent.

Properties

Property	Description
`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` Required 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

{
    baseAmount: '2000',
    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 CANCEL_SALE CANCEL_REFUND TOKENIZE_CARD CARD_PAN CANCEL_TRX MOTO_SALE MOTO_REFUND MOTO_REVERSAL SALE_AND_TOKENIZE_CARD UPDATE PRINT_RECEIPT

Objects

Transaction Result Object​

Balance​

Bypass Options​

Device​

Acquirer​

Transaction Status​

Options​

Sale Options​

Refund Options​

Merchant Auth Options​

Merchant Auth​

Merchant Auth Credential​

Financial Status​

Device Status​

Currency​

Card Entry Type​

Card Scheme Name​

Verification Method​

Payment Scenario​

Status Info​

Status​

Tender Type​

Tip Configuration​

Transaction Type​

Transaction Result Object

Balance

Bypass Options

Device

Acquirer

Transaction Status

Options

Sale Options

Refund Options

Merchant Auth Options

Merchant Auth

Merchant Auth Credential

Financial Status

Device Status

Currency

Card Entry Type

Card Scheme Name

Verification Method

Payment Scenario

Status Info

Status

Tender Type

Tip Configuration

Transaction Type