Objects
Transaction Result
TransactionResult Object
An object holding information about the result of a transaction.
signatureUrl: In case the signature can not be updated to the Handpoint servers and an URL is not generated, the terminal will send back the image binary in base64 format to your software. It is important to be able to support both the URL and the image binary format.
customerReceipt and merchantReceipt: The receipts are usually received as URLs in the transaction result from the terminal. Please note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and an URL is not generated then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats.
Properties
| Parameter | Description |
|---|---|
addressVerification AddressVerification | AVS (Address Verification Service) result, present only when the acquirer performed one. |
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. |
transactionReference String | The transaction reference used to query the Handpoint Gateway directly to know the outcome of the transaction in case the result is not delivered. Must be saved on your end as a fallback. Not returned for linked refunds or reversals (those share the reference of the original transaction). |
batchNumber String | Batch number of the transaction. |
accountType String | Account type used for the transaction. |
applicationLabel String | Application label from the card. |
customData String | Custom data field, can be used to pass additional information. |
Code example
{
"addressVerification": {
"resultCode": "FULL_MATCH"
},
"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
}
Address Verification
AddressVerification Object
Address verification (AVS) result for a MoTo transaction, exposed on TransactionResult.
Properties
| Parameter | Description |
|---|---|
resultCode AvsResultCode | Outcome of the AVS check performed by the acquirer |
Code example
{
"resultCode": "FULL_MATCH"
}
Avs Result Code
AvsResultCode Enum
An enum representing the outcome of an Address Verification Service (AVS) check performed by the acquirer for a MoTo transaction.
Possible values
FULL_MATCH EXACT_MATCH ADDRESS_MATCH ZIP_MATCH ZIP9_MATCH NO_MATCH UNSUPPORTED INTERNATIONAL RETRY UNAVAILABLE UNKNOWN
Balance
Balance Object
Balance available on the card
Properties
| Parameter | Description |
|---|---|
amount Integer | The amount balance |
currencyCurrency | The balance currency |
signBalanceSign | 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')
Billing
Billing Object
Billing address details attached to a MoTo transaction, used for Address Verification Service (AVS) checks.
Properties
| Parameter | Description |
|---|---|
zipCode Required String | The billing postal/ZIP code |
address String | The billing street address. Optional; used for AVS when provided |
Code example
Billing billing = new Billing("90210", "123 Main Street");