Skip to main content
Version: Next

Objects

Acquirer

Acquirer Enum

An enum representing the supported acquirers for merchant authentication

AMEX BORGUN EVO OMNIPAY POSTBRIDGE INTERAC TSYS VANTIV SANDBOX

Balance

Balance Object

Balance available on the card.

Properties

PropertyDescription
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

PropertyDescription
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
}
}

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

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

Device

Device Object

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

Properties

PropertyDescription
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"
}

Device Status

DeviceStatus Object

A class which holds the payment terminal status.

Properties

PropertyDescription
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"
}

Financial Status

FinancialStatus Enum

An enum representing different statuses for a completed 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.

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

PropertyDescription
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

PropertyDescription
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"
}

Merchant Auth Options

MerchantAuthOptions Object

An object to store merchant authentication options for regular operations.

Properties

PropertyDescription
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"
}
],
}

Metadata

Metadata Object

An object to store metadata.

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

{
"metadata": {
"metadata1": "data1",
"metadata2": "data2",
"metadata3": "data3",
"metadata4": "data4",
"metadata5": "data5"
}
}

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

PropertyDescription
fullName Required
String
First and last name of the money transfer recipient.(a-Z, A-Z only)
countryCode Required
CountryCode
Country code of the recipient (ISO 3166-1 alpha-3)
{
"moneyRemittanceOptions":{
"fullName":"John Doe",
"countryCode":"USA"
}
}

Operation Start Result

OperationStartResult Object

Object containing information about the financial operation being performed.

Properties

ParameterDescription
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.
transactionResult
String
Promise that will resolve/reject with Transaction Result object.

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

PropertyDescription
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

{
"customerReference": "MyCustomReference",
"metadata": {
"metadata1": "data1",
"metadata2": "data2",
"metadata3": "data3",
"metadata4": "data4",
"metadata5": "data5"
}
}

Payment Scenario

PaymentScenario Enum

An enum representing different types of payment scenario.

Possible values

UNKNOWN MAGSTRIPE MAGSTRIPECONTACTLESS CHIP CHIPCONTACTLESS CHIPFAILMAGSTRIPE MOTO

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

PropertyDescription
customerReference
String
An arbitrary string to use as your own identifier for a transaction.
duplicate_check
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 will automatically be prompted on the payment terminal if a suspicious charge is detected. We are only prompting the duplicate 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_check functionality is available for the following transaction types: Sale, Sale and Tokenize, Sale Reversal, Refund, Refund Reversal, MoTo Sale, MoTo Refund and MoTo Reversal.

The duplicate_check service is enabled to "true" by default, if you want to disable it, you must explicitly pass the duplicate_check flag as part of the transaction request with the value "false".
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).
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

{
"customerReference": "MyCustomReference",
"duplicate_check": false,
"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"
}
],
"metadata": {
"metadata1": "data1",
"metadata2": "data2",
"metadata3": "data3",
"metadata4": "data4",
"metadata5": "data5"
},
"moneyRemittanceOptions":{
"fullName":"John Doe",
"countryCode":"USA"
}
}

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

PropertyDescription
customerReference
String
An arbitrary string to use as your own identifier for a transaction.
duplicate_check
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 will automatically be prompted on the payment terminal if a suspicious charge is detected. We are only prompting the duplicate 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_check functionality is available for the following transaction types: Sale, Sale and Tokenize, Sale Reversal, Refund, Refund Reversal, MoTo Sale, MoTo Refund and MoTo Reversal.

The duplicate_check service is enabled to "true" by default, if you want to disable it, you must explicitly pass the duplicate_check flag as part of the transaction request with the value "false".
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).
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

{
"customerReference": "MyCustomReference",
"duplicate_check": false,
"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"
}
],
"metadata": {
"metadata1": "data1",
"metadata2": "data2",
"metadata3": "data3",
"metadata4": "data4",
"metadata5": "data5"
},
"moneyRemittanceOptions":{
"fullName":"John Doe",
"countryCode":"USA"
}
}

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

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

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

PropertyDescription
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 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

PropertyDescription
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
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 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",
"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,
"cardHolderName": "cardholder name"
}

Transaction Status

TransactionStatus Object

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

Properties

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

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

Verification Method

VerificationMethod Enum

An enum representing different cardholder verification methods.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED MOBILE_PASS_CODE