[*ReportConfiguration*](androidobjects.md#19) | This parameter specifies the filter to get transactions report.| + +**Code example** + +```java +//Get the transactions report for device "12345", from 30th April 2021 at 00:00:00, to 30th April 2021 at 23:59:59, in eurs: +List terminalSerialNumber = new ArrayList<>(); +terminalSerialNumber.add("0821122334"); +ReportConfiguration configuration = new ReportConfiguration("EUR", "20231001000000", "20231201235959", "+00:00", terminalSerialNumber); + +api.getTransactionsReport(configuration); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +The report will be returned to the registered ReportResult interface. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the command was processed successfully. `False` if the sending was not successful.| + +## Flash Reset + +`deleteDeviceConfig` Method + +Sends a command to the payment terminal to delete its configuration. + +**Code example** + +```java +api.deleteDeviceConfig(); +``` + +## Print Receipt + +`printReceipt` Method + +Print on demand functionality allowing the merchant to print any HTML formatted receipt. It is possible to print images or barcodes as well as passing directly a URL to the printReceipt function. A bitmap can also be printed, in order to do so it needs to be rendered as an image and inserted into the html. + +:::tip +Receipts received in the terminal transaction result can either be a URL **OR** an HTML formatted receipt. The format can be changed by updating the `getReceiptsAsURLs` boolean when initializing the SDK [*Settings*](androidobjects.md#settings). 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. +::: + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `receipt` Required
*String* | The receipt must match the following [HTML Print Format](https://handpoint.atlassian.net/wiki/spaces/PD/pages/1409875969/Html+Print+Format). The Transaction Report (also called End of Day Report) can be printed from the string returned in the [ReportResult](androideventlisteners.md#reportResult) event.| + +**Code example (Prints a receipt with Handpoint logo)** + +```java +//Print a receipt with Handpoint logo (bitmap format) +String validReceipt = "
";
+boolean success = api.printReceipt(validReceipt);
+```
+
+ **Returns**
+
+| Parameter | Notes |
+| ----------- | ----------- |
+| `Boolean`| `True` if the receipt was sent to the printer, false otherwise.|
+
+
+## Search Devices
+
+`searchDevices` Method
+
+Starts the search of payment terminals associated with the specified ConnectionMethod.
+
+**Parameters**
+
+
+| Parameter | Notes |
+| ----------- | ----------- |
+| `method` Required [*ConnectionMethod*](androidobjects.md#20) | The type of connection with the payment terminal (Bluetooth, Cloud, etc.).| + +**Code example** + +```java +// Starts the search for payment terminals. +// You must implement Events.DeviceDiscoveryFinished and subscribe +// to the event delegate in order to receive the result +api.searchDevices(ConnectionMethod.XXX); +``` + +**Events invoked** + +[**deviceDiscoveryFinished**](androideventlisteners.md#deviceDiscoveryFinished) + +Returns a list of payment terminals. + +## Set Locale + +`setLocale` Method + +Sets the SDK Locale (language). It is used to set the SDK language as well as the associated date and number formatting. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `locale` Required
[*SupportedLocales*](androidobjects.md#23) | The locale to be set. Supported locales are: SupportedLocales.en_CA, SupportedLocales.en_UK, SupportedLocales.en_US, SupportedLocales.hr_HR, SupportedLocales.is_IS, SupportedLocales.fr_FR, SupportedLocales.pt_PT, SupportedLocales.it_IT, SupportedLocales.no_NO, SupportedLocales.de_DE, SupportedLocales.sl_SL, SupportedLocales.et_EE| + + + + + **Code example** + +```java +// Set canadian english +api.setLocale(SupportedLocales.en_CA); +``` + +## Set log level + +`setLogLevel` Method + +Sets the log level (info, debug...) for both the payment terminal and the SDK. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `level *`
[*LogLevel*](androidobjects.md#18) | The desired log level. Can be LogLevel.None, LogLevel.Info, LogLevel.Full, LogLevel.Debug| +| `device`
[*Device*](androidobjects.md#17) | This parameter specifies to the system which device should be used for the operations. If no device is supplied, the system will attempt to use a default one.| + +**Code example** + +```java +//Sets the log level to info +api.setLogLevel(LogLevel.info); +``` + +**Events invoked** + +**None** + +No events are invoked. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` iif the operation was successfully sent to device.| + + + + +## Stop current transaction + +`stopCurrentTransaction` Method + +Stops the current transaction. A transaction can be stopped only if the last [currentTransactionStatus](androideventlisteners.md#14) event reported has the property **isCancelAllowed** set to **true**. +This operation is **not supported** for **Hilite and Hi5** devices. + +**Code example** + +```java +// Stops current transaction +if (api.stopCurrentTransaction()) { + ... +} else { + ... +} +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked after stop transaction. Status **UserCancelled** will be reported. + +[**endOfTransaction**](androideventlisteners.md#16) + +Transaction will fail with status **CANCELLED** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the transaction was successfully stopped, false otherwise.| + + +## Update device + +`update` Method + +The update operation checks for new software or configuration updates and initiates a download if required. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device`
[*Device*](androidobjects.md#17) | This parameter specifies to the system which payment terminal should be used for the operation. If no device is supplied, the system will attempt to use a default one.| + +**Code example** + +```java +//Check for card reader update +api.update(); +``` + +**Events invoked** + +**None** + +The merchant should be notified about the update process. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + +## Get Transaction Status{#getTransactionStatus} + +`getTransactionStatus` Method + +**This functionality is only available for SmartPos devices (PAX).** + +If for any reasons you do not know if a transaction was approved or declined then this method will allow you to retrieve the status of the transaction from the Handpoint gateway. The `getTransactionStatus` method is a convenient way to retrieve the current status of a transaction based on its unique reference. This method accepts a `transactionReference` as a parameter and returns the current status of the transaction. The `transactionReference` is returned at the start of a transaction, as part of the [Operation Start Result](androidobjects.md#OperationStartResult) object. + +The main [*FinancialStatus*](androidobjects.md#34) that can be returned as a response to this method are the following ones: + +- AUTHORISED - Transaction was successful. +- DECLINED - Transaction was declined. +- UNDEFINED (NOT FOUND) - 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. +- IN_PROGRESS - The transaction has been received by the gateway but the outcome is not known yet, try again after a few seconds. +- REFUNDED - Transaction was refunded. + + + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `transactionReference` Required
*String* | The `transactionReference` ([UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))) is returned at the start of a transaction, as part of the [Operation Start Result](androidobjects.md#OperationStartResult) object.| + + +**Code example** + +```java +//Gets the current status of a transaction +api.getTransactionStatus("00000000-0000-0000-0000-000000000000"); +``` + +**Events invoked** + +[**transactionResultReady**](androideventlisteners.md#transactionResultReady) + +Invoked when the result of the getTransactionStatus request is available. +*** + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| \ No newline at end of file diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.7/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androideventlisteners.md @@ -0,0 +1,731 @@ +--- +sidebar_position: 8 +id: androideventlisteners +--- + + + + +# Events Listeners + +## SmartposRequired + +`Events.SmartposRequired` Interface + +You must provide a class implementing this interface when initializing the SDK for a smartPOS terminal (PAX/Telpo). + +**Code example** + +```java +public final class EventHandler implements Events.SmartposRequired { + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + @Override + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Events** + + [`ConnectionStatusChanged`](#connectionStatusChanged)[`CurrentTransactionStatus`](#14)[`EndOfTransaction`](#16) [`PendingResults`](#pendingResults) + + +## MposRequired + +`Events.MposRequired` Interface + +You must provide a class implementing this interface when initializing the SDK for an mPOS terminal (HiLite). + +**Code example** + +```java +public final class EventHandler implements Events.MposRequired { + @Override + public void deviceDiscoveryFinished(List devices) { ... } + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + @Override + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + @Override + public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Events** + + [`ConnectionStatusChanged`](#connectionStatusChanged)[`CurrentTransactionStatus`](#14)[`EndOfTransaction`](#16) [`PendingResults`](#pendingResults) [`DeviceDiscoveryFinished`](#deviceDiscoveryFinished) [`SignatureRequired`](#15) + +## PosRequired + +`Events.PosRequired` Interface + +You must provide a class implementing this interface when initializing the SDK when supporting both mPOS and SmartPOS terminals (PAX/Telpo & HiLite). + +**Code example** + +```java +public final class EventHandler implements Events.PosRequired { + @Override + public void deviceDiscoveryFinished(List devices) { ... } + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + @Override + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + @Override + public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Events** + + [`ConnectionStatusChanged`](#connectionStatusChanged)[`CurrentTransactionStatus`](#14)[`EndOfTransaction`](#16) [`PendingResults`](#pendingResults) [`DeviceDiscoveryFinished`](#deviceDiscoveryFinished) [`SignatureRequired`](#15) + + +## Card Brand Display{#cardBrandDisplay} + +`Events.CardBrandDisplay` Interface + +An interface which needs to be implemented and added as a listener to get events providing information on the supported card brands and/or the card brand used during the transaction. + +**Methods** + +`supportedCardBrands( List
*List `
+ +`readCard( CardBrands usedCard );` + +| Parameter | Notes | +| ----------- | ----------- | +| `usedCard` Required
[*CardBrands*](androidobjects.md#cardBrands) | Name of the card brand| + +**Code example** + +```java +public final class EventHandler implements Events.CardBrandDisplay { + + @Override + public void supportedCardBrands(List cardBrandsList) { + // Get supported card brands + } + + @Override + public void readCard(CardBrands usedCard) { + // Get the used card brand + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Card Tokenization + +`Events.CardTokenization` Interface + +Implement this interface in order to receive events about the card tokenization. + +**Methods** + +`cardTokenized( ResumeCallback callback, CardTokenizationData cardTokenizationData)` + +| Parameter | Notes | +| ----------- | ----------- | +| `callback` Required
*ResumeCallback* | Lets the SDK continue the operation| +| `cardTokenizationData` Required
[*CardTokenizationData*](androidobjects.md#card-tokenization-data) | Object with the tokenization data.| + +```java +public final class EventHandler implements Events.CardTokenization { + + @Override + public void cardTokenized(@NonNull ResumeCallback callback, @NonNull CardTokenizationData cardTokenizationData) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Connection status changed{#connectionStatusChanged} + +`Events.ConnectionStatusChanged` Interface + +Implement this interface in order to receive connection status changes. + +**Methods** + +`connectionStatusChanged( ConnectionStatus status , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `status` Required
[*ConnectionStatus*](androidobjects.md#connection-status) | New status of the connection| +| `device` Required
[*Device*](androidobjects.md#17) | The terminal which sent this information.| + + +**Code example** + +```java +public final class EventHandler implements Events.ConnectionStatusChanged { + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + + + +## Current transaction status{#14} + +`Events.CurrentTransactionStatus` Interface + +Implement this interface in order to receive events about the current transaction. + +**Methods** + +`currentTransactionStatus( StatusInfo status , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `status` Required
[*StatusInfo*](androidobjects.md#status-info) | The **StatusInfo** of the current transaction| +| `device` Required
[*Device*](androidobjects.md#17) | The terminal the request is sent from.| + + +**Code example** + +```java +public final class EventHandler implements Events.CurrentTransactionStatus { + + @Override + public void currentTransactionStatus(StatusInfo info, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Device capabilities ready{#deviceCapabilitiesReady} + + +`Events.DeviceCapabilitiesReady` Interface + +Implement this interface in case the payment terminal needs to notify the SDK of its capabilities + +**Methods** + +`deviceCapabilities( DeviceCapabilities capabilities , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `capabilities` Required
[*DeviceCapabilities*](androidobjects.md#24) | The capabilities of the terminal| +| `device` Required
[*Device*](androidobjects.md#17) | The terminal sending its capabilities| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceCapabilitiesReady { + + @Override + public void deviceCapabilities(DeviceCapabilities capabilities, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + + +## Device discovery finished{#deviceDiscoveryFinished} + +`Events.DeviceDiscoveryFinished` Interface + +Implement this interface in order to receive a list of available payment terminals. The event handler defined in this interface is invoked after calling the method searchDevices + +**Methods** + +`deviceDiscoveryFinished( List
List `
[*TransactionResult*](androidobjects.md#25) | Holds all the information about the transaction.| +| `device` Required
[*Device*](androidobjects.md#17) | The payment terminal.| + + +**Code example** + +```java +public final class EventHandler implements Events.EndOfTransaction { + + @Override + public void endOfTransaction(TransactionResult result, Device device) { + // Check the status of the transaction, save it, ... + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Hardware status changed{#hardwareStatusChanged} + +`Events.HardwareStatusChanged` Interface + +Implement this interface in order to receive events when the hardware status changes. + +**Methods** + +`hardwareStatusChanged( HardwareStatus status , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `status` Required
*HardwareStatus* | New status of the hardware.| +| `device` Required
[*Device*](androidobjects.md#17) | The payment terminal.| + + +**Code example** + +```java +public final class EventHandler implements Events.HardwareStatusChanged { + + @Override + public void hardwareStatusChanged(HardwareStatus status, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Log{#log} + +`Events.Log` Interface + +An interface which needs to be implemented and added as a listener to receive logging information. + +**Extends** + +[`OnMessageLogged`](#onMessageLogged) + +**Code example** + +```java +public final class EventHandler implements Events.Log { + + @Override + public void deviceLogsReady(String logs, Device device) { ... } + @Override + public void onMessageLogged(LogLevel level , String message) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## MessageHandling{#messageHandling} + +`Events.MessageHandling` Interface + +An interface which needs to be implemented and added as a listener to get events which are called when the sdk asks the application to display or hide a message. + +**Methods** + +`showMessage( String message , Boolean dismissible , int duration );` + +| Parameter | Notes | +| ----------- | ----------- | +| `message` Required
*String* | Message to display| +| `dismissible` Required
*Boolean* | A flag that indicates whether the message can be dismissed| +| `duration` Required
*int* | The timeout to hide the message. In milliseconds, if 0 is sent, the message should not auto dismiss.| + + +`hideMessage( String message );` + +| Parameter | Notes | +| ----------- | ----------- | +| `message` Required
*String* | Message to hide| + +**Code example** + +```java +public final class EventHandler implements Events.MessageHandling { + + @Override + public void showMessage(String message, Boolean dismissible, int duration) { + // Show message for a 'duration' period (if duration = 0 DO NOT dismiss until hideMessage(String message) event is received) and make it dismissible if the input marks it as possible + } + + @Override + public void hideMessage(String message) { + // Hide the message + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` +## On message logged{#onMessageLogged} + +`Events.OnMessageLogged` Interface + +Implement this interface to receive logs from the payment terminal. +**Methods** + +`onMessageLogged( LogLevel level , String message );` + +| Parameter | Notes | +| ----------- | ----------- | +| `level` Required
[*LogLevel*](androidobjects.md#18) | The LogLevel of the logging| +| `message` Required
*String* | The log trace which was logged by the SDK.| + + +**Code example** + +```java +public final class EventHandler implements Events.OnMessageLogged { + + @Override + public void onMessageLogged(LogLevel level, String message) { + // Process log trace + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## PhysicalKeyboardEvent{#physicalKeyboardEvent} + +`Events.PhysicalKeyboardEvent` Interface + +An interface which needs to be implemented and added as a listener to get events coming from the PAX A80 physical keyboard. + +** Methods** + +`onKeyPressed( PaxA80Keys key );` + +| Parameter | Notes | +| ----------- | ----------- | +| `key` Required
[*PaxA80Keys*](androidobjects.md#28) | The name of the key that has been pressed| + + +**Code example** + +```java +public final class EventHandler implements Events.PhysicalKeyboardEvent { + + @Override + public void onKeyPressed(String key) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## PendingResults{#pendingResults} + +`Events.PendingResults` Interface + +An interface which needs to be implemented and added as a listener to receive information about pending TransactionResults. In case of a communication failure between the SDK and the payment terminal there might be a result pending from the transaction which did not get sent to the SDK. + +**Code example** + +```java +public final class EventHandler implements Events.PendingResults { + + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Extends** + +[`TransactionResultReady`](#transactionResultReady) + +## PaymentProvider + +`Events.PaymentProvider` Interface + +An interface which needs to be implemented and added as a listener to receive all available events related to financial operations. + +**Extends** + +[`SignatureRequired`](#15) [`EndOfTransaction`](#16) [`OnMessageLogged`](#onMessageLogged) [`CurrentTransactionStatus`](#14) + + +## PrinterEvents{#printerEvents} + +`Events.PrinterEvents` Interface + +An interface which needs to be implemented and added as a listener to get events coming from the printer. + +**Methods** + +`printSuccess( );` + + + +`printError(PrintError error);` + +| Parameter | Notes | +| ----------- | ----------- | +| `error` Required
[*PrintError*](androidobjects.md#29) | Enum detailing the reason of the error| + +**Code example** + +```java +public final class EventHandler implements Events.PrinterEvents { + + @Override + public void printSuccess() { + // Successful print action + } + + @Override + public void printError(PrintError error) { + // Unable to perform print action due to error + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Report result{#reportResult} + +`Events.ReportResult` Interface + +Implement this interface to receive an event when a report result from a [getTransactionsReport](androiddevicemanagement.md#getTransactionReport) is returned. + +**Methods** + +`reportResult( TypeOfResult type , String report , DeviceStatus status , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `type` Required
[*TypeOfResult*](androidobjects.md#30) | The type of the report| +| `report` Required
*String* | The text of the report| +| `status` Required
[*DeviceStatus*](androidobjects.md#33) | The status of the device| +| `device` Required
[*Device*](androidobjects.md#17) | The terminal sending the report| + + +**Code example** + +```java +public final class EventHandler implements Events.ReportResult { + + @Override + public void reportResult(TypeOfResult type, String report, DeviceStatus status, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Events** + +[`DeviceDiscoveryFinished`](#deviceDiscoveryFinished) [`SignatureRequired`](#15) [`EndOfTransaction`](#16) [`PendingResults`](#pendingResults) + +## Signature required{#15} + +`Events.SignatureRequired` Interface + +The SignatureRequired interface must be implemented in order to receive an event when a card requires a signature as a verification method. This interface is only required for an Hilite integration, PAX and Telpo terminals automatically prompt for signature capture on the terminal. + +**Methods** + +`signatureRequired( SignatureRequest request , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `request` Required
[*SignatureRequest*](androidobjects.md#signature-request) | Holds the signature request.| +| `device` Required
[*Device*](androidobjects.md#17) | The payment terminal.| + + +**Code example** + +```java +public final class EventHandler implements Events.SignatureRequired { + + @Override +public void signatureRequired(SignatureRequest signatureRequest, Device device) { + // Save merchant receipt + String merchantReceipt = signatureRequest.getMerchantReceipt(); + api.signatureResult(true); + } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Status{#status} + +`Events.Status` Interface + +An interface which needs to be implemented and added as a listener to receive connection and transaction statuses. + +**Code example** + +```java +public final class EventHandler implements Events.Status { + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + @Override + public void hardwareStatusChanged(HardwareStatus status, Device device) { ... } + @Override + public void currentTransactionStatus(StatusInfo info, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +**Extends** + +[`ConnectionStatusChanged`](#connectionStatusChanged) [`HardwareStatusChanged`](#hardwareStatusChanged) [`CurrentTransactionStatus`](#14) + +## Transaction result ready{#transactionResultReady} + +`Events.TransactionResultReady` Interface + +Implement this interface in order to receive an event after a pending TransactionResult has been recovered from the payment terminal. + +**Methods** + +`transactionResultReady( TransactionResult transactionResult , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `transactionResult` Required
[*TransactionResult*](androidobjects.md#25) | A ***TransactionResult*** is containing all information about the recovered transaction.| +| `device` Required
[*Device*](androidobjects.md#17) | The payment terminal.| + + +**Code example** + +```java +public final class EventHandler implements Events.TransactionResultReady { + + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## Transaction started{#transactionStarted} + +`Events.TransactionStarted` Interface + +Implement this interface in order to receive an event when a transaction is started through the Cloud API channel. + +**IMPORTANT NOTE**: This interface is **only** available for cloud-enabled devices. See [DeviceCapabilitiesReady](#deviceCapabilitiesReady) interface. + +**Methods** + + +`transactionStarted( TransactionType transactionType , BigInteger amount , Currency currency, String transactionReference );` + +| Parameter | Notes | +| ----------- | ----------- | +| `transactionType` Required
[*TransactionType*](androidobjects.md#31) | Type of transaction started| +| `amount` Required
*BigInteger* | Amount in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the transaction started| +| `transactionReference` Required
*String* | The transaction reference of the started transaction. `transactionReference` will be empty if the operation has not been started with one, or if it is an operation to which it does not apply (a tokenization, for example)| + +**Code example** + +```java +public final class EventHandler implements Events.TransactionStarted { + + //If the transactionReference has NOT been included in the request, it will be empty. + @Override +public void transactionStarted(TransactionType type, BigInteger amount, Currency currency, String transactionReference) { + // Notify the app user transaction has been started ... + } +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.7/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androideventsubscribers.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 7 +id: androideventsubscribers +--- + + +# Events Subscribers + +## Register events delegate + +`registerEventsDelegate` Method + +Registers a delegate for the SDK events. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `listener` Required
*Object* | Any object implementing one or more of the available delegate interfaces.| + +**Code example** + +```java +public class ObjectHelper implements Events.SmartposRequired, Events.Status, Events.Log, Events.TransactionStarted, Events.CurrentTransactionStatus, Events.ConnectionStatusChanged, Events.EndOfTransaction, Events.TransactionResultReady { + ... + private void setEventsHandler() { + // Register this class as listener for events + this.api.registerEventsDelegate(this); + ... + } + +} +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the new delegate was added successfully.| + + + +## Unregister events delegate + +`unregisterEventsDelegate` Method + +Unregisters an object from SDK events. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `listener` Required
*Object* | Any object implementing one or more of the available delegate interfaces.| + +**Code example** + +```java +public class ObjectHelper implements Events.SmartposRequired, Events.Status, Events.Log, Events.TransactionStarted, Events.CurrentTransactionStatus, Events.ConnectionStatusChanged, Events.EndOfTransaction, Events.TransactionResultReady { + ... + private void unsubscribeEventsDelegate() { + // Stop receiving events + this.api.unregisterEventsDelegate(this); + ... +} +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the new delegate was removed successfully.| + + diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidintegrationguide.md new file mode 100644 index 0000000..d9114a4 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidintegrationguide.md @@ -0,0 +1,820 @@ +--- +sidebar_position: 4 +id: androidintegrationguide +--- + + +# Integration Guides + + +**The SDK supports the following connection methods:** + +1. **[Android Native (PAX/Telpo)](#8)** +2. **[Bluetooth (HiLite)](#9)** +3. **[USB (BluePad 50+)](#10)** + +## Android Native Integration (PAX/Telpo) {#8} + + **Introduction** + +This tutorial is guiding you through all the required steps to create a basic payment application for Android Payment devices such as PAX and Telpo. + +The new generation of Handpoint SDK's is designed to make your life easier. Simple and created for humans, it does not require any specific knowledge of the payment industry to be able to start accepting card payments. + +At Handpoint we take care of securing every transaction so you don´t have to worry about it while creating your application. We encrypt data from the payment terminal to the bank with our point-to-point encryption solution. Our platform is always up to the latest PCI security requirements. + +:::warning +Please, start an operation (sale,refund etc.) ONLY if you have received the **InitialisationComplete** message from the **currentTransactionStatus** method +::: + +**Let's start programming!** + +**1. Modify the AndroidManifest.xml** + +We **strongly** recommend you add the following to your `AndroidManifest.xml`: + +- Inside the tag **`
+android.enableJetifier=true
+android.useAndroidX=true +::: + + +**3. Create a Java class** + +Create a new java class called `HandpointDelegate.java` and include `com.handpoint.api.*` as a dependency: + +```java +package com.yourpackage.name; + +import com.handpoint.api.HandpointCredentials; +import com.handpoint.api.Hapi; +import com.handpoint.api.HapiFactory; +import com.handpoint.api.shared.ConnectionMethod; +import com.handpoint.api.shared.ConnectionStatus; +import com.handpoint.api.shared.Currency; +import com.handpoint.api.shared.Device; +import com.handpoint.api.shared.Events; +import com.handpoint.api.shared.SignatureRequest; +import com.handpoint.api.shared.StatusInfo; +import com.handpoint.api.shared.TipConfiguration; +import com.handpoint.api.shared.TransactionResult; +import com.handpoint.api.shared.agreements.Acquirer; +import com.handpoint.api.shared.agreements.Credential; +import com.handpoint.api.shared.agreements.MerchantAuth; +import com.handpoint.api.shared.options.SaleOptions; + +import java.math.BigInteger; +import java.util.Arrays; +import java.util.List; + +//Check all the events available in the Events interface. +//If you want to subscribe to more events, just add to the list of implemented interfaces. +public class HandpointDelegate implements Events.SmartposRequired, Events.CurrentTransactionStatus, Events.ConnectionStatusChanged, Events.EndOfTransaction, Events.TransactionResultReady { + + private Hapi api; + + public HandpointDelegate(Context context) { + initApi(context); + } + + public void initApi(Context context) { + String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret); + this.api = HapiFactory.getAsyncInterface(this, context, handpointCredentials); + // The api is now initialized. Yay! we've even set default credentials. + // The shared secret is a unique string shared between the payment terminal and your application, it is unique per merchant. + // You should replace this default shared secret with the one sent by the Handpoint support team. + + //Since we're running inside the terminal, we can create a device ourselves and connect to it + Device device = new Device("some name", "address", "", ConnectionMethod.ANDROID_PAYMENT); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + //Connection Status connected + + } + } + + public OperationStartResult pay() { + return this.api.sale(new BigInteger("1000"), Currency.GBP); + // Let´s start our first payment of 10.00 pounds + // Use the currency of the country in which you will be deploying terminals + } + + public OperationStartResult payWithOptions() { + SaleOptions options = new SaleOptions(); + + // Adding tipping + TipConfiguration config = new TipConfiguration(); + //Optionally + config.setHeaderName("HEADER"); + //Optionally + config.setFooter("FOOTER"); + //Optionally + config.setEnterAmountEnabled(true); + //Optionally + config.setSkipEnabled(true); + //Optionally + config.setTipPercentages(Arrays.asList(5, 10, 15, 20)); + options.setTipConfiguration(config); + + // Adding Multi MID / Custom merchant Authentication + MerchantAuth auth = new MerchantAuth(); + Credential credential = new Credential(); + //Optionally + credential.setAcquirer(Acquirer.SANDBOX); + //Optionally + credential.setMid("mid"); + //Optionally + credential.setTid("tid"); + //Add as many credentials as Acquirers your merchant have agreements with + auth.add(credential); + options.setMerchantAuth(auth); + + //Add a customer reference + options.setCustomerReference("Your customer reference"); + + //Enable pin bypass + options.setPinBypass(true); + + //Enable signature bypass + options.setSignatureBypass(true); + + //Define a budget number + options.setBudgetNumber("YOUR_BUDGET_NUMBER"); + + return this.api.sale(new BigInteger("1000"),Currency.GBP, options); + // Let´s start our first payment of 10.00 pounds + // Use the currency of the country in which you will be deploying terminals + } + + public boolean getTrxStatus() { + //Allows you to know the status of a transaction by providing the transactionReference. + //The transactionReference must be a unique identifier (UUID v4). + //This functionality is only available for SmartPos devices (PAX) + return api.getTransactionStatus("00000000-0000-0000-0000-000000000000"); + //You will receive the TransactionResult object of this operation in transactionResultReady event + } + + @Override + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { + if (statusInfo.getStatus() == StatusInfo.Status.InitialisationComplete) { + // The StatusInfo object holds the different transaction statuses like reading card, pin entry, etc. + // Let's launch a payment + pay(); + } + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The TransactionResult object holds details about the transaction as well as the receipts + // Useful information can be accessed through this object like the transaction ID, the amount, etc. + } + + @Override + public void transactionResultReady(TransactionResult transactionResult, Device device) { + // Pending TransactionResult objects will be received through this event if the EndOfTransaction + // event was not delivered during the transaction, for example because of a network issue. + // Here you are also going to receive a TransactionResult object after making a query to getTransactionStatus + } + + public void disconnect(){ + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +**We're done!** + +Sort of. With the above tutorial you've done a basic integration that can perform sale transactions. + +Explore the rest of the documentation to see more transaction types supported and possibilities. + +## Bluetooth Integration (HiLite) {#9} + + **Introduction** + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an HiLite payment terminal. + +The new generation of Handpoint SDK's is designed to make your life easier. Simple and created for humans, it does not require any specific knowledge of the payment industry to be able to start accepting credit/debit card transactions. + +At Handpoint we take care of securing every transaction so you don´t have to worry about it while creating your application. We encrypt data from the payment terminal to the bank with our point-to-point encryption solution. Our platform is always up to the latest PCI-DSS security requirements. + +:::warning +Please, start an operation (sale,refund etc.) ONLY if you have received the **InitialisationComplete** message from the **currentTransactionStatus** method +::: + + + +**Let's start programming!** + +**1. Modify the AndroidManifest.xml** + +We **strongly** recommend you add the following to your `AndroidManifest.xml`: + +- Inside the tag **`
+
+
+
+
+
+
+ Android SDK
+
+ 
+
+
+
+ + +:::tip +If you are currently using 6.x of the Android SDK, take a look at the [migration guide](androidmigrationguide.md) to 7.x +::: + + +The new generation of Handpoint APIs and SDKs are engineered to make your life simpler and happier. + +**Awesomely simple** + +Created for humans, coders, geeks, no need of a dark and complex knowledge of the payment industry. + +
+ +**Super secure** + +We take care of PCI compliance so you can be kept out of PCI scope. The Handpoint terminals encrypt all sensitive cardholder data so your app does not have to deal with it. + +### SDK distribution + +The Handpoint Android SDK is available on the Handpoint internal Nexus server which contains both the **production builds** and **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to use the development Snapshots, listed as -RC.X-SNAPSHOT for example **7.1010.3-RC.1-SNAPSHOT** +- If you are integrating your software with a **PAX production terminal** or with a **HiLite terminal** you will need to use the Production versions listed eg **7.1010.3** + +If in doubt regarding what version to use, we always recommend using the latest available production version, for development snapshots the recommendation is to use the latest RC (highest number) that matches the latest production SDK version published. Our support team is also available to answer any questions regarding what version to use. + +The Handpoint Android SDK is compatible with Android version 5.1.1 [(API level 22)](https://developer.android.com/about/versions/lollipop/android-5.1) and up. +The latest version is compiled with java **1.8** + + + +### AndroidManifest.xml + +We **strongly** recommend you add the following to your `AndroidManifest.xml`: + +- Inside the tag **`
*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) | Balance available on the card.| +| `budgetNumber`
*String* | Used to split payments over a period of months.| +| `cardEntryType`
[*CardEntryType *](#22) | Method used by the terminal to read the card.| +| `cardLanguagePreference`
*String* | Preferred language of the card (EMV tag 5F2D).| +| `cardSchemeName`
[*CardSchemeName*](#32) | 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*](#13) | 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*](#33) | 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*](#34) | 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*](#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*](#35) | 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*](#36) | 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*](#31) | 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*](#38) | 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** + + +```json +{ + "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{#21} + +`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** + +```java +public enum Acquirer { AMEX, + BORGUN, + EVO, + OMNIPAY, + POSTBRIDGE, + INTERAC, + TSYS, + VANTIV, + SANDBOX +} +``` + +## Balance + +`Balance` Object + +Balance available on the card + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `amount`
*Integer* | The amount balance | +| `currency`
*Currency*| The balance currency | +| `sign`
[*BalanceSign*](#balance-sign) | Positive (C) or negative (D) balance. You can retrieve the balance sign using the methods isPositive() or isNegative() | + +**Code example** + +```java +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} + +`CardBrands` Enum + +A string representing the supported card brands. + +**Possible values** + +`VISA` `MASTERCARD` `MAESTRO` `AMEX` `DISCOVER` `DINERS` `JCB` `INTERAC` `OTHER` + + +## Card Entry Type{#22} + +`CardEntryType` Enum + +An enum representing different card entry types. + +**Possible values** + +`UNDEFINED` `MSR` `ICC` `CNP` + +## Card Scheme Name{#32} + +`CardSchemeName` Enum + +A string representing different card brands. + +**Possible values** + +`MasterCard` `Visa` `Maestro` `American Express` `Discover` `JCB` `Diners` `UnionPay` `Interac` + + +## Card Tokenization Data + +`CardTokenizationData` Object + +An object representing the tokenized card. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `token`
*String* | Token representing the card number| +| `expiryDate`
*String*| Expiration date of the card| +| `tenderType`
[*TenderType*](#36) |ternder type of the card (credit/debit) | +| `issuerCountryCode`
*CountryCode* | The country code of the issuer of the card [(ISO 3166-1)](https://en.wikipedia.org/wiki/ISO_3166-1) | + +## Connection Method{#20} + +`ConnectionMethod` Enum + +An enum representing different connection methods with the payment terminal. + +Currently `BLUETOOTH`, `ANDROID_PAYMENT` and `USB` are the only supported types. + +**Possible values** + +`BLUETOOTH` `ANDROID_PAYMENT` `USB` + +**Code example** + +```java +//Currently BLUETOOTH, ANDROID_PAYMENT and USB are the only connection methods available. +public enum ConnectionMethod { + BLUETOOTH, + ANDROID_PAYMENT, + USB +} +``` + +## Connection Status + +`ConnectionStatus` Enum + +A list of connection statuses. Note: the events starting with Cloud[...] are exclusively for devices linked to merchants with CLOUD Api key (CLOUD mode enabled) and can be safely ignored for Android native integrations. + +**Possible values** + +`Connected` `Connecting` `Disconnected` `Disconnecting` `NotConfigured` `Initializing` `CloudConnected` `CloudInitialized` `CloudAvailable` `CloudDisconnected` `CloudUnavailable` + +## Currency{#13} + +`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{#17} + +`Device` Object + +An object to store the information about the payment terminal in use. + +**Methods** + +**Constructor** + +```java +Device(String name, String address, UsbDevice usbDevice, ConnectionMethod connectionMethod, String sharedSecret, int timeout); +``` + +| Parameter | Notes | +| ----------- | ----------- | +| `name` Required
*String* | A name to identify the device| +| `address` Required
*String* | The address of the device you wish to connect to. E.g.: "08:00:69:02:01:FC" for bluetooth or just an identifier if your application is running directly on a PAX or Telpo device (ConnectionMethod.ANDROID_PAYMENT).| +| `usbDevice` Required
*UsbDevice* | Represents a concrete attached USB device.| +| `connectionMethod` Required
[*ConnectionMethod *](#20) | Type of connection with the payment terminal. E.g: Bluetooth| +| `sharedSecret`
*String* | Replaces the default shared secret proviced in the initialization step.| +| `timeout`
*int* | The number of miliseconds until a connection is considered timed out. If not set, the default timeout is 15 seconds.| + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `Id *`
*String* | A unique identifier for the payment terminal.| + + + +**Code example** + +```java +//Create and init a new Datecs Device +Device dev = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); + +//Create and init a new PAX/Telpo Device for a ANDROID_PAYMENT connection +Device dev = new Device("LocalPaxOrTelpo", "LocalHost", "null", ConnectionMethod.ANDROID_PAYMENT); +``` + +## Device Capabilities{#24} + +`DeviceCapabilities` Object + +An object holding the capabilities of the payment terminal. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `printer`
*Boolean* | True if the terminal has printer, false otherwise| +| `cloudApi`
*Boolean*| True if the terminal is cloud-enabled, false otherwise| + +## Device Parameter + +`DeviceParameter` Enum + +An enum describing all the admin commands to send to a payment terminal. + +**Possible values** + +`BluetoothName` `BluetoothPass` `SystemTimeout` `ScreenTimeout` `SignatureTimeout` + +## Device Status{#33} + +`DeviceStatus` Object + +A class which holds the status of the payment terminal. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `SerialNumber`
*String* | Gets the serial number of the payment terminal| +| `BatteryStatus`
*String* | Gets the battery status of the payment terminal (in percentages)| +| `BatterymV`
*String* | Gets the battery voltage of the payment terminal| +| `BatteryCharging`
*String* | Gets the battery charging status of the payment terminal| +| `ExternalPower`
*String* | Gets the status of the payment terminal external power| +| `ApplicationName`
*String* | Gets the application name of the payment terminal| +| `ApplicationVersion`
*String* | Gets the application version of the payment terminal| + +## Financial Status{#34} + +`FinancialStatus` Enum + +An enum representing different statuses of a finalized transaction + +**Possible values** + +`UNDEFINED` `AUTHORISED` `DECLINED` `PROCESSED` `FAILED` `CANCELLED` `PARTIAL_APPROVAL` `IN_PROGRESS` `REFUNDED` `CAPTURED` + + +Description of the different financial statuses: + +| Parameter | Notes | +| ----------- | ----------- | +| `UNDEFINED` (NOT FOUND)
| Any financial status other than the below mentioned financial statuses will be `UNDEFINED`. The `UNDEFINED` (NOT FOUND) status can be returned as a response to the [get transaction status](androiddevicemanagement.md#getTransactionStatus) 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](androiddevicemanagement.md#getTransactionStatus) 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](androiddevicemanagement.md#getTransactionStatus) 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](androidtransactions.md#pre-auth-capture) 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](androiddevicemanagement.md#getTransactionStatus) method. + +## Handpoint Credentials{#43} + +`HandpointCredentials` Object + +A class containing the credentials used to communicate with the payment terminal, essentially the shared secret (always required). +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `sharedSecret`
*String* | `String` the value of the Shared secret.| + + +**Code example** + +```java +{ + String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret); + //We've even set a default shared secret! +} +``` + +## Handpoint API (Hapi) Factory + +`HapiFactory` Object + +A factory to provide a unified entrypoint and simplify the instantiation of the Hapi object. + +**Methods** + +**Static factory** +getAsyncInterface( Events.Required requiredListener , Context context , HandpointCredentials handpointCredentials ); + +| Parameter | Notes | +| ----------- | ----------- | +| `requiredListener` Required
[*Events.Required*](androideventlisteners.md#42) | A listener object to report the required events.| +| `context` Required
*Context* | The Android context.| +| `handpointCredentials` Required
[*HandpointCredentials*](#43) | An object containing the actor's shared secret key.| + + +**Code example** + +```java +//InitApi for Datecs devices or PAX/Telpo ConnectionMethod.ANDROID_PAYMENT +public void InitApi() +{ + String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + api = HapiFactory.getAsyncInterface(this, new HandpointCredentials(sharedSecret)); + //The api is now initialized. Yay! we've even set a default shared secret +} +``` + +## Hapi Manager + +`HapiManager` Object + +A static class containing information about the current status of the SDK + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `DefaultSharedSecret`
*String* | Gets the default shared secret in use.| +| `LogLevel`
[*LogLevel*](#18) | 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** + +```java +//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{#18} + +`LogLevel` Enum + +An enum describing the different levels of logging available. + +**Possible values** + +`None` `Info` `Full` `Debug` + +## Manufacturer{#manufacturer} + +`Manufacturer` Enum + +A string representing different payment terminal supported manufacturers. + +**Possible values** + +`INVALID` `DATECS` `PAX` `TELPO` + +## MerchantAuth{#37} + +`MerchantAuth` Object + +An object to store merchant authentication. + +**Methods** + +```java +Constructor +MerchantAuth( ); +``` + +```java +Constructor +MerchantAuth( Credential credential ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
[*Credential*](#40) | If present, adds the given credential to the list.| + +```java +Constructor +MerchantAuth( List
*List
[*Credential*](#40) | The credential to be added.| + +**Code example** + +```java +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{#40} + +`Credential` Object + +An object to store credentials (Acquirer, Mid, Tid, MCC and ExternalId) for merchant authentication. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `acquirer`
[*Acquirer *](#21) | 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** + +```java +// 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} + +`MerchantAuthOptions` Object + +An object to store merchant authentication options for regular operations. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `MerchantAuth`
[*MerchantAuth*](#37) | An object containing all the credentials used to optionally authenticate a merchant| + +**Code example** + +```java +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} + +`Metadata` Object + +An object to store metadata. This field can be used to pass custom data to the Handpoint gateway, it will be echoed back in the transaction result. This field will also be part of the transaction response if querying the Handpoint transaction reporting API. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `metadata1`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata2`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata3`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata4`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata5`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| + +**Code example** + +```java +// Option 1 +Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5"); + +// Option 2 +Metadata metadata = new Metadata(); +metadata.setMetadata1("Data 1"); +metadata.setMetadata2("Data 2"); +metadata.setMetadata3("Data 3"); +metadata.setMetadata4("Data 4"); +metadata.setMetadata5("Data 5"); +``` + + +## Money Remittance Options + +`MoneyRemittanceOptions` Object + +An object representing options for Mastercard money remittance transactions. The recipient's first and last name and the recipient's country code are mandatory for Mastercard transactions processed by merchants with category codes 4829 and 6540. VISA transactions do not require money remittance options to be sent. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `fullName` Required
*String* | first and last name of the recipient of the funds| +| `countryCode` Required
*CountryCode* | Country code of the recipient of the funds [(ISO 3166-1 alpha-3)](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)| + +**Code example** + +```java +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +``` + +## MoTo Channel + +`MoToChannel` Enum + +A enum representing the channel used for the card not present transaction (MO = Mail Order / TO = Telephone Order) . + +**Possible values** + +`MO` `TO` + +## MoTo Options + +`MoToOptions` Object + +An object to store optional parameters for card not present (MoTo) transactions. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `Channel`
[*MoToChannel*](#moto-channel) | 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*](androidobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + + + +**Code example** + +```java +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 Payment Operation. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `sale`
[*Sale*](androidtransactions.md#2) | A sale sends a payment request to the payment terminal.| +| `refund`
[*Refund*](androidtransactions.md#5) | A refund operation moves funds from the merchant account to the cardholder´s credit card.| +| `saleReversal`
[*Sale Reversal*](androidtransactions.md#4) | A sale reversal, also called sale VOID allows the user to reverse a previous sale operation.| +| `refundReversal`
[*Refund Reversal*](androidtransactions.md#6) | A refund reversal, also called refund VOID allows the merchant to reverse a previous refund operation.| + + + +## Operation Start Result {#OperationStartResult} + +`OperationStartResult` Object + +Object containing information about the financial operation being performed. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `operationStarted`
*boolean* | `true` if the operation has started. false otherwise | +| `transactionReference`
*String* | The `transactionReference` **must** be saved on your end in case you do not get back the transaction result object at the end of the transaction. The `transactionReference` will allow you to query the Handpoint Gateway directly to know the outcome of the transaction in case it is not delivered as planned by the terminal at the end of the transaction. A linked refund or a reversal will **not** return a `transactionReference` because the transaction reference for those types of transactions is the same as the one received for the original financial operation.| +| `errorMessage`
*String* | Detailed reason for the transaction error. | + + +## Optional Transaction Parameters + +`OptionalParameters` Object + +A class containing optional transaction parameters supported by the payment terminal. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `Budget`
*String* | **Budget is only available for sale transactions.** A `String` representing the key for a budget number.A budget number can be used to split up an amout over a period of months. The value has to be a `String` of 2 digits representing the number of months to split the transaction to.| +| `CustomerReference`
*String* | **CustomerReference is available for all transactions.** A `String` representing the key for a customer reference.A customer reference can be used for an internal marking system. The value is sent as a `String` of a maximum 25 characters and received back when the transaction has been processed.| + +## Options{#7} + +`options` Object + +An object to store customer reference options for regular operations. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `Metadata`
[*Metadata*](#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** + +```java +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{#35} + +`PaymentScenario` Enum + +An enum representing different types of scenario. + +**Possible values** + +`UNKNOWN` `MAGSTRIPE` `MAGSTRIPECONTACTLESS` `CHIP` `CHIPCONTACTLESS` `CHIPFAILMAGSTRIPE` `MOTO` + +## PAX A80 Keys{#28} + +`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*](#4) + +## Print Error{#29} + +`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{#6} + +`RefundOptions` Object + +An object to store all the customization options for a refund. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `MerchantAuth`
[*MerchantAuth*](#37) | 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*](#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*](androidobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + +**Code example** + +```java +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{#19} + +`ReportConfiguration` Object + +An object to store all the configuration for a transactions report. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `currency`
[*Currency*](#13) | 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** + +```java +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{#4} + +`SaleOptions` Object + +An object to store all the customization options for a sale. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `BudgetNumber`
*String* | The budget number can be used to split payments over a period of months.| +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `MerchantAuth`
[*MerchantAuth*](#37) | 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*](#39) | 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*](#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*](androidobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + +**Code example** + +```java +SaleOptions options = new SaleOptions(); + +//If you use a customer reference +options.setCustomerReference("Your customer reference"); + +//If you need Multi MID / Custom merchant Authentication +MerchantAuth auth = new MerchantAuth(); +Credential credential = new Credential(); +//Optionally +credential.setAcquirer(YOUR_ACQUIRER); +//Optionally +credential.setMid(mid); +//Optionally +credential.setTid(tid); +//Add as many credentials as acquirers your merchant supports (for example OMNIPAY/AMEX). +auth.add(credential); +options.setMerchantAuth(auth); + +//If you need to enable pin bypass +options.setPinBypass(true); + +//If you need to disable the duplicate payment check service +options.setCheckDuplicates(false); + +//If you want to specify the budget period +//Only available for SureSwipe +options.setBudgetNumber(YOUR_BUDGET_NUMBER); + +//If you want to specify tip options +//Only available for PAX and Telpo terminals. +TipConfiguration config = new TipConfiguration(); +//Optionally +config.setHeaderName(HEADER); +//Optionally +config.setFooter(FOOTER); +//Optionally +config.setEnterAmountEnabled(true); +//Optionally +config.setSkipEnabled(true); +config.setTipPercentages(percentages); +options.setTipConfiguration(config); + +//Alternatively, you can set the tip amount directly +options.setTipConfiguration(new TipConfiguration(AMOUNT)); + +// Metadata +Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5"); +options.setMetadata(metadata); + +//Adding Money Remitance options +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +SaleOptions saleOptions = new SaleOptions(true,moneyRemittanceOptions); +``` + +## Sale and Tokenize Options + +`SaleAndTokenizeOptions` Object + +An object to store all the customization options for a sale and tokenize options. + +| Parameter | Description | +| ----------- | ----------- | +| `BudgetNumber`
*String* | The budget number can be used to split payments over a period of months.| +| `CustomerReference`
*String* | An arbitrary string to use as your own identifier for a transaction| +| `MerchantAuth`
[*MerchantAuth*](#37) | 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*](#39) | 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*](androidobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + +**Code example** + +```java +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} + +`Settings` Object + +An Object holding the SDK initialization settings + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `automaticReconnection`
*boolean* | When this property is set to true, the SDK will automatically try to reconnect to the terminal after disconnection. The SDK maintains internally a reconnection thread which keeps on trying to connect until it succeeds. The delay between reconnections is exponentially increased on every new attempt. The default value for this property is **false**| +| `autoRecoverTransactionResult`
*boolean* | The default value for this property is **false**| +| `sendToDeviceMaxAttempts`
*Integer* | Number of retry attemps when there is an error communicating with the card reader. The default value for this property is **3**| +| `timeBetweenAttempts`
*Integer* | Time in milliseconds between attempts. The default value for this property is **5000**| +| `showSDKUIComponents`
*boolean* | The default value for this property is **false**| +| `getReceiptsAsURLs`
*boolean* | The default value for this property is **false**| + + +## Signature Request + +`SignatureRequest` Object + +A class containing information about a signature verification. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `timeout`
*int* | `int` the value of the timeout in seconds.| +| `MerchantReceipt`
*String* | `String` the merchant receipt as html. Note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats. | + +## Status {#45} + +`status` Enum + +An enum containing information about the status of a transaction. + +**Possible values** + +`Undefined` `Success` `InvalidData` `ProcessingError` `CommandNotAllowed` `NotInitialised` `ConnectTimeout` `ConnectError` `SendingError` `ReceivingError` `NoDataAvailable` `TransactionNotAllowed` `UnsupportedCurrency` `NoHostAvailable` `CardReaderError` `CardReadingFailed` `InvalidCard` `InputTimeout` `UserCancelled` `InvalidSignature` `WaitingForCard` `CardInserted` `ApplicationSelection` `ApplicationConfirmation` `AmountValidation` `PinInput` `ManualCardInput` `WaitingForCardRemoval` `TipInput` `SharedSecretInvalid` `SharedSecretAuth` `WaitingSignature` `WaitingHostConnect` `WaitingHostSend` `WaitingHostReceive` `WaitingHostDisconnect` `PinInputCompleted` `PosCancelled` `RequestInvalid` `CardCancelled` `CardBlocked` `RequestAuthTimeout` `RequestPaymentTimeout` `ResponseAuthTimeout` `ResponsePaymentTimeout` `IccCardSwiped` `RemoveCard` `ScannerIsNotSupported` `ScannerEvent` `BatteryTooLow` `AccountTypeSelection` `BtIsNotSupported` `PaymentCodeSelection` `PartialApproval` `AmountDueValidation` `InvalidUrl` `WaitingCustomerReceipt` `PrintingMerchantReceipt` `PrintingCustomerReceipt` `UpdateStarted` `UpdateFinished` `UpdateFailed` `UpdateProgress` `WaitingHostPostSend` `WaitingHostPostReceive` `Rebooting` `PrinterOutOfPaper` `ErrorConnectingToPrinter` `CardTapped` `ReceiptPrintSuccess` `InvalidPinLength` `OfflinePinAttempt` `OfflinePinLastAttempt` `ProcessingSignature` `CardRemoved` `TipEntered` `CardLanguagePreference` `AutomaticPrintingStarted` `CancelOperationNotAllowed` `UpdateSoftwareStarted` `UpdateSoftwareFinished` `UpdateSoftwareFailed` `UpdateSoftwareProgress` `InstallSoftwareStarted` `InstallSoftwareFinished` `InstallSoftwareFailed` `InstallSoftwareProgress` `UpdateConfigStarted` `UpdateConfigFinished` `UpdateConfigFailed` `UpdateConfigProgress` `InitialisationComplete` + +## Status Info + +`statusInfo` Object + +A class containing information about the status of the transaction. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `isCancelAllowed`
*Boolean* | A `boolean` letting the integrator know if the terminal will accept a stop transaction request.| +| `status`
[*Status*](#45) | A `Status` enum representing the status of the transaction.| +| `cardLanguage`
[*SupportedLocales*](#23) | 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*](#33) | A `DeviceStatus` object containing information about the payment terminal.| + +## Supported Locales{#23} + +`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{#36} + +`TenderType` Enum + +An enum representing different tender types. + +**Possible values** + +`NOT_SET` `CREDIT` `DEBIT` + + +## Tip Configuration{#39} + +`TipConfiguration` Object + +**Constructor** + +TipConfiguration( String tipAmount ); + +| Parameter | Notes | +| ----------- | ----------- | +| `tipAmount`
*String* | If present, the amount of the tip to be used for the transaction.| + + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `amount`
*BigInteger* | Transaction amount in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `baseAmount`
*BigInteger* | Base amount used to calculate the tip - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). If no base amount is defined, the transaction amount is used as base amount.| +| `headerName`
*String* | Name of the tipping menu appearing on the terminal. Default: Tip| +| `tipPercentages`
*List
*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** + +```json +{ + "amount": "2000", + "baseAmount": "2000", + "headerName": "", + "tipPercentages": [5,10,15,20,25], + "enterAmountEnabled": true, + "skipEnabled": false, + "footer": "Thank you!!! ;)" +} +``` + + +## Transaction Type{#31} + +`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{#30} + +`TypeOfResult` Enum + +An enum representing different types of device reports. + +**Possible values** + +`STATUS` `REPORT` `BLUETOOTHNAME` `EMVCONFIGURATION` + +## Verification Method{#38} + +`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` + + diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidreleasenotes.md new file mode 100644 index 0000000..9fda179 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidreleasenotes.md @@ -0,0 +1,481 @@ +--- +sidebar_position: 2 +id: androidreleasenotes +--- + + + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + + +## 7.1010.7 +**Fixes** + +- Deprecated coroutines APIs have been removed to improve compatibility for integrators + + +## 7.1010.6 +**Features**: + +- Partial reversals are supported now + +- Support for PAX A3700 reader has been added + +**Fixes** + +- Processing misalignment between SDK and Gateway has been fixed + + +## 7.1010.5 +**Features**: + +A new `cardPresent` flag is supported in Integrated mode, which comes from our [REST API](/restapi/restintroduction) or its related Cloud clients [JavaScript SDK](/javascript/javascriptintroduction) and [Windows SDK](/windows/windowsintroduction). This new flag allows to indicate the payments flow that a Reversal operation will imply an actual present card. Please see [Handling card present reversals with Elavon acquirers](https://handpoint.atlassian.net/wiki/spaces/PD/pages/5104533505/Handling+card+present+reversals+with+Elavon+acquirers) for further information on the purpose of this flag. + + +## 7.1010.3 +**Fixes**: + +Some timeout-ed authorization requests in the reader were still reaching the gateway. This was causing double charges. + + +## 7.1010.2 +**Fixes**: + +Network stability has been improved + + +## 7.1010.1 +**Features**: + +"Cash" and "Other" transaction types now have a Transaction ID + +**Fixes**: + +- A scenario where double charges could happen has been fixed + +- The customer receipt now is fully in the card's language (when the language tag is available) + +- Some Fiserv and Elavon certification issues have been addressed + + +## 7.1009.5 +**Features**: + +We're excited to announce the latest update to our Android SDK, featuring support of ***Tokenized Payments Operations***, as well as supporting a new PAX card readers model: **IM25**. This new Tokenized Payments Operations feature is an expansion of our former Tokenize and Modify feature, fully replacing and complementing it. + +**Tokenized Payments Operations** enable merchants to securely capture a customer's card information (without storing the raw card details) and use that token to immediately perform a payment-related operation. This streamlines loyalty flows, subscriptions, refunds, or reversals while keeping card data safe and PCI-compliant. + +Thanks to our new Tokenize Payments Operations feature, integrators can now first tokenize card, and right after this, apply their own bussiness logic before resuming the operation to decide how the final operation will be according to customer's loyalty points, current discount policy, or some other particular use cases. + +There are two main modes for how this works, depending on integration needs: Standalone or Cloud. + +- [Standalone Tokenized Payments Operations](androidtransactions.md#standalone-tokenized-payments-operations). In this mode, Android SDK integrators can directly use the methods this SDK offers in the app they are building on top of it, to implement their loyalty, subscriptions or related uses logic. + +- [Cloud Tokenized Payments Operations](androidtransactions.md#cloud-tokenized-payments-operations). In this mode, Tokenized Payments Operations methods and flows of the Android SDK are commanded via our Cloud clients, which can be either [REST API](/restapi/restintroduction), [JavaScript SDK](/javascript/javascriptintroduction) or [Windows SDK](/windows/windowsintroduction). This allows to execute all operations programmatically, offering seamless integration with their existing workflows. + + +**Fixes**: + +- Several EMV certification issues have been addressed + +- Transaction Result was not being delivered in some cases. Now it is working properly in all use cases. + +- Refunds and Reversals didn't include the transactionReference field. This has been fixed. + + +## 7.1008.6 +**Fixes**: + +- Some translations have been corrected, as well as error messages from our Gateway + + +## 7.1008.4 +**Fixes**: + +- Several minor stability issues have been fixed + + +## 7.1008.3 +**Features**: + +- In account type selection, the order is first "Credit" and then "Debit" now. + +**Fixes**: + +- An issue with the remove card event has been addressed + + +## 7.1008.1 +**Fixes**: + +- Several certification issues have been addressed + + +## 7.1008.0 +**Features**: + +- Brightness level control is offered as a public method now + +- Internal payments libraries of PAX devices have been updated + +**Fixes**: + +- Some EMV related issues have been solved + +- Volume controls were accessible during payment signature screen in some use cases where the shouldn't + + +## 7.1006.3 +**Fixes**: + +- Signature was missing in receipts in some use cases + + +## 7.1006.2 +**Fixes**: + +- Several minor stability issues have been fixed + + +## 7.1006.1 +**Fixes**: + +- Fix for language selection menu (only for Interac cards) + + +## 7.1006.0 +**Features**: + +- Now just "CARD" in shown in receipts when the card brand is not in the language library + +**Fixes**: + +- Tokenize and Modify: A second "remove card" was being displayed after providing phone number + +- Some EMV related issues have been solved + + +## 7.1005.4 +**Fixes**: + +- The RRN was missing in the ReceiptDataKeeper object + + +## 7.1005.3 +**Fixes**: + +- Several minor stability issues have been fixed + + +## 7.1005.2 +**Fixes**: + +- Operations with 0 amount and/or tip supported + +- Receipt uploaded event's behavior has been fixed + +- Transactions corrections + +- Minor fixes in tokenization + + +## 7.1005.1 +**Fixes**: + +- Several minor stability issues have been fixed + + +## 7.1005.0 +**Features**: + +- Speed improvements: We're excited to announce the release of Handpoint Android SDK version **7.1005.0**, focused on delivering significant improvements in transaction processing speeds. This update empowers your app to handle transactions quicker and more efficiently, enhancing the overall user experience for your customers. + +- Enhanced Cloud Mode Performance: Cloud initialization will now be faster, leading to quicker overall transaction processing. Cloud transactions will benefit from these optimizations as well. + +:::caution +**Cloud Mode** users: There might be a short delay in accessing your receipt after a transaction is completed in Cloud Mode. While the transaction itself will process successfully, the receipt URL you receive might return a 404 error message for a few seconds after the transaction finishes. +::: + +## 7.1004.2 +**Features**: + +Automatic Refunds. These new methods empowers users to seamlessly process refunds without the need for any physical card or card details. + +- [Automatic Refund](androidtransactions.md#automatic-refund), users can effortlessly initiate a refund transaction without requiring the cardholder to dip, tap, or swipe their card. Users only need to pass the Original Transaction ID (GUID) to the Automatic Refund function. The system will automatically process the refund, and the refunded amount will mirror the original sale amount, simplifying the entire refund process. + + +- [Automatic Partial Refunds](androidtransactions.md#automatic-partial-refund). This operation allows you to PARTIALLY refund a card automatically without requiring the cardholder to dip/tap/swipe his card. In its simplest form you only have to pass the amount, currency and the Original Transaction ID (GUID). + + + By eliminating the need for physical card involvement, Automatic Refund streamlines the refund process, saving time for both merchants and customers. This efficiency boost enhances overall transaction management, contributing to a more seamless and customer-centric experience. + + +**Fixes**: + +- Inconsistency when formatting currencies using Slovenian as the locale. + + +## 7.1004.1 +**Features**: + +We're excited to announce the latest update to our Android SDK, featuring support of Mastercard MoneySend fields for money remittance merchants. In order to use this functionality, we provide you with an object called [Money Remittance Options](androidobjects.md#money-remittance-options) which must be sent for all Mastercard transactions. + +The supported operations are Sale, Sale & Tokenize, Refund, Linked Refunds, Reversals, MoTo Sale, MoTo Refund. For Linked Refunds and Reversals, Money Remittance fields should be taken from the original Sale/MoTo/Refund when using the field `originalTransactionID`. + +***Please note**: Money Remittance is available only for some acquirers and geographies. Please check with your Handpoint relationship manager about the availability of this functionality for your merchants. + +## 7.1004.0 +**Features**: + +We are introducing a new transaction type called [Pre-Authorization](androidtransactions.md#pre-auth). A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + +A pre-authorized transaction can be increased or decreased ([Pre-Auth Increase](androidtransactions.md#pre-auth-increasedecrease)), for example if a tab was opened and the consumer is adding new orders going above the initial pre-authorized amount. + +A pre-authorized transaction can be captured ([Pre-Auth Capture](androidtransactions.md#pre-auth-capture)) to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank. + +A pre-authorized transaction can be fully released ([Pre-Auth Reversal](androidtransactions.md#pre-authcapture-reversal)), for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged + +We are also introducing the [Tokenize And Modify](androidtransactions.md#tokenize-and-modify) operation. A tokenize and modify operation allows you to start a financial operation for an initial amount, tokenize the card being dipped/tapped/swiped and modify the amount before the transaction is sent for processing. This feature allows you to bring your own loyalty engine and apply for example an instant discount at the point of sale for loyal customers. + + +## 7.1002.0 +**Features**: + +We are introducing a new feature called [Get Transaction Status](androiddevicemanagement.md#getTransactionStatus). This new feature allows you to query the Handpoint Gateway for the status of a transaction at any given time. For example, in case of an app crash, timeout, or connection problem, you are now able to use the [transaction reference](androidobjects.md#OperationStartResult) returned at the start of a financial operation to get the status of a transaction in real time. You can use this feature to track the progress of your payments and troubleshoot any issues that may arise. This feature is available for all payment methods and currencies. + +- Cloud integrations: A new parameter called `transactionReference` has been added to the [transactionStarted](androideventlisteners.md#transactionStarted) method. This means that when implementing this method in a class, you need to update the method signature to include the new parameter. + +Added Estonian language 🇪🇪 + + +## 7.1001.0 +**Features**: + + We are introducing a new feature called [Transaction Metadata](androidobjects.md#metadata). This new feature helps the customer to persist and echo back some data that belongs to the customer business domain at transaction time. The Transaction Metadata is sent in the request and echoed back in the response from the gateway. In addition, customers will be able to use the Transaction Metadata to search matching transactions from our Transaction Feed API.***** + +The Transaction Metadata feature will be available when the Handpoint Android SDK **v7.1001.0** or higher is used. + +***Please note**: Transactions will be available in TXN Feed API only if the request has reached the gateway. + +- German language support. +- Support for PAX A800 devices. + +**Fixes**: +- Bug related to automatic printing. +- Log improvements. + +## 7.0.2 + +**Features**: +- Norwegian and Italian language support. + +**Fixes**: +- Card reader capabilities identification. +- Kiosk mode management. +- Log improvements for support purposes. + +## 7.0.1 + +- Removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) +- All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal. +- Introducing a new feature called **duplicate payment check**. +- The `deviceCapabilities` event has been renamed to `supportedCardBrands` +- For more information please check our [migration guide](androidmigrationguide.md). + +## 6.7.4 + +- `customerReference` correctly populated when card is removed in the middle of a transaction +- MOTO: Correct handling of expired access and refresh tokens +- CLOUD: Channel connection/subscription handling + +## 6.7.3 + +**Fixes**: +- MOTO: Linked Refund only with GUID. +- Correctly populated transaction result the `originalEFTTransactionID` on Linked Refunds. +- Correctly populated on transaction result amounts on "Already reversed" operations. +- Crashes identified in the field. + + +## 6.7.2 + +**Fixes**: +- MOTO: Retry token and configuration download if missing for MoTo transactions +- CLOUD: device status moving terminals between merchants. +- CLOUD: REST-API transaction result delivery. +- `requestedAmount` field in Transaction Result correctly populated. + + +## 6.7.0 + +**Features** +- A35 support added +- Swedish language support +- Field customerReference added to TransactionResult + +**Fixes**: +- Cloud client shows "Unable to process your request" while the request reach the device +- Contactless card tokenization fixed +- CVM fixed in receipts for MOTO transactions +- Amount fields are now populated in case of FAILURE and DECLINE +- Interact/AMEX certification fixes +- Fix minor issues and app crashes + +## 6.6.7 +**Fixes**: +- SCA scenarios on PAX A80 +- CLOUD: receipt printing +- Deadman mechanism for not completed trx. App dies in the middle of a trx, will be auto cancelled in the restart + +## 6.6.3 + +**Fixes**: +- DATECS: Stop reconnection loop on api.disconnect() + +## 6.6.0 + +**Features**: + - MoTo (Mail Order Telephone Order) + +**Fixes**: + - CLOUD: Connection stability. + - AID parsing for Discover cards. + - PIN input on physical keyboards. + + +## 6.5.0 + +**Features**: + - Card brand display: 2 new events deviceCapabilities (supportedCardBrands) and readCard to show the supported card brands and card used during a transaction respectively. + - Update webview for devices that do not support co-branding. + +**Fixes**: + - Correct handling of stopCurrentTransaction operation result for cloud operations. + - Pin bypass for contactless transactions. + - Automatic reconnection logic for android Datecs devices. + +## 6.4.1 + +**Fixes**: +- Automatic Cancellation parameters. + + + +## 6.4.0 + +**Features**: +- Populate operation timeout on CLOUD operations. +- Max attempts on Cancellation retries. +- Generic screen to show text messages. + +**Fixes**: +- Base amount handling in TipDialog +- Cancellation service max retry window +- Verification method on transaction result object +- Correct population of MessageReasonCode +- Error message multi-language translation +- Cardholder name for contact operations +- Amount presentation in transactions report +- Analytics and Cloud services stability moving terminals between merchants + +**Refactor**: + +- Deprecated jcenter repository +- Improved structure of cryptography module +- Legacy code removal + +## 6.3.0 + + **Features**: + +- Print Report v2. +- PAXA80 physical keyboard full support. +- Deadman mechanism for not completed trx. +- Addition of customer reference on transaction result for cancelled of timed out trx + +**Fixes**: + +- Certification scenarios. +- Unification of sdk dialogs styles. +- Card reading during tokenizations. +- Contactless light thread handling. +- Xml parsing. +- Printing html using uncommon characters. +- Monospace font for printing. +- SCA cases on contact. +- PAX A80 Pin bypass handling. +- Receipts for partial approvals. +- Correct message on empty config update. + + **Refactor**: + +- Internal Emv Classes to improve performance. +*** + +## 6.2.2 + +**Fixes**: + +- Compatibility issues with Android 11 devices. +- CLOUD: Improved logic to wake up device and start trx during device sleep mode. +*** + +## 6.2.1 + +**Fixes**: + +- Improved bluetooth connection logic (Datecs) +*** + + + +## 6.2.0 + +**Features**: + +- New Tip Dialog. +- Multi-mid Phase 2. +- Physical Keyboard PAX-A80. +- Visa debit US app selection. +- cardHolderName filed in Transaction Result object + +**Fixes**: + +- Temporarily block during consecutive operations (Datecs devices). +- Translations. +- Compatibility with Android 11. +*** + + +## 6.1.1 + +**Fixes**: + +- Translations +*** + + + +## 6.1.0 + +**Features**: + +- End of the day report. +- New printing framework. +- Transaction limit exceeds event. +- Multi-language in Status and End of Transaction → Transaction Result new fields: multiLanguageStatusMessages and multiLanguageErrorMessages. +- Support for MerchantAuth and Bypass options for Cloud + REST-API. + +**Fixes**: + +- Receipt adjustments for mobile wallets. +- Receipt adjustments for empty tags. +- Fields in TransactionResult. +- Contactless lights after card reading error. +- REST-API ACK. +- Translations +- Error handling prior connecting to device diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidtransactions.md @@ -0,0 +1,2028 @@ +--- +sidebar_position: 5 +id: androidtransactions +--- + +# Transaction Types + + +## Sale{#2} + +`Sale` + +A sale initiates a payment operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts tip configuration and a map with extra parameters. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `options`
[*SaleOptions*](androidobjects.md#4) | An object to store all the customization options for a sale ([Tip Configuration](androidobjects.md#39), [Metadata](androidobjects.md#metadata), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate a sale for 10.00 in Great British Pounds +api.sale(new BigInteger("1000"),Currency.GBP); + +//Initiate a sale for 10.00 in Great British Pounds with a tipping configuration +//This feature is only available for PAX and Telpo devices +TipConfiguration tipConfiguration = new TipConfiguration(); +tipConfiguration.setTipPercentages(Arrays.asList(5, 10, 15, 20)); +tipConfiguration.setTipAmount(new BigInteger("1000")); +tipConfiguration.setBaseAmount(new BigInteger("1000")); +tipConfiguration.setEnterAmountEnabled(true); +tipConfiguration.setFooter("Thank you"); +tipConfiguration.setSkipEnabled(true); +// Metadata +Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5"); + +SaleOptions options = new SaleOptions(); +options.setTipConfiguration(tipConfiguration); +options.setMetadata(metadata); + +api.sale(new BigInteger("1000"),Currency.GBP, options); + + +//Initiate a sale for 10.00 USD using Money Remitance options +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +SaleOptions saleOptions = new SaleOptions(true, moneyRemittanceOptions); + +api.sale(new BigInteger("1000"), Currency.USD, saleOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**signatureRequired**](androideventlisteners.md#15) + +Invoked if card verification requires signature. +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Sale And Tokenize Card{#3} + +A [sale](#2) operation which also returns a card token. (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice) + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `options`
[*SaleAndTokenizeOptions*](androidobjects.md#sale-and-tokenize-options) | An object to store all the customization options for a sale ([Tip Configuration](androidobjects.md#39), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate a sale for 10.00 in Great British Pounds +SaleOptions options = new SaleAndTokenizeOptions(); +api.sale(new BigInteger("1000"),Currency.GBP, options); + + +//Initiate a sale for 10.00 in Great British Pounds with a tipping configuration +//This feature is only available for PAX and Telpo devices + +TipConfiguration tipConfiguration = new TipConfiguration(); +tipConfiguration.setTipPercentages(Arrays.asList(5, 10, 15, 20)); +tipConfiguration.setTipAmount(new BigInteger("1000")); +tipConfiguration.setBaseAmount(new BigInteger("1000")); +tipConfiguration.setEnterAmountEnabled(true); +tipConfiguration.setFooter("Thank you"); +tipConfiguration.setSkipEnabled(true); +SaleOptions options = new SaleOptions(); +options.setTipConfiguration(tipConfiguration); +options.toSaleAndTokenizeOptions(); + +api.sale(new BigInteger("1000"),Currency.GBP,options); + +//Initiate a sale for 10.00 USD using Money Remitance options +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +SaleAndTokenizeOptions saleAndTokenizeOptions= new SaleAndTokenizeOptions(moneyRemittanceOptions); + +api.sale(new BigInteger("1000"), Currency.USD, saleAndTokenizeOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**signatureRequired**](androideventlisteners.md#15) + +Invoked if card verification requires signature. +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + + **Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + + +## Sale Reversal{#4} + +`saleReversal` + +A sale reversal, also called sale VOID allows the user to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. In its simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionID` Required
*String* | Id of the original sale transaction| +| `options`
[*SaleOptions*](androidobjects.md#4) | An object to store all the customization options for a sale.| + +**Code example** + +```java +//Initiate a reversal for 10.00 in Great British Pounds +api.saleReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000"); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**signatureRequired**](androideventlisteners.md#15) + +Invoked if card verification requires signature. +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Refund{#5} + +`refund` + +A refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters. Note that a card is required to be swiped, dipped or tapped for this operation. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionID`
*String* | If present it links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.| +| `options`
[*RefundOptions*](androidobjects.md#6) | An object to store all the customization options for a refund ([Metadata](androidobjects.md#metadata), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate a refund for 10.00 in Great British Pounds (Linked Refund) +api.refund(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000"); + +//Initiate a refund for 10.00 USD using Money Remitance options (Linked Refund) +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +RefundOptions refundOptions= new RefundOptions(true, moneyRemittanceOptions); + +api.refund(new BigInteger("1000"), Currency.GBP, "00000000-0000-0000-0000-000000000000", refundOptions); +``` + +** Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry') +*** + +[**signatureRequired**](androideventlisteners.md#15) + +Invoked if card verification requires signature. +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Automatic Refund + +`automaticRefund` + +A refund operation moves funds from the merchant account to the cardholder's credit card. This operation allows you to refund a card automatically without requiring the cardholder to dip/tap/swipe his card. In its simplest form you only have to pass the Original Transaction ID (GUID) to this function. The amount to be refunded will be the same amount as the one of the original sale. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*String* | Links the automatic refund with a previous sale. The amount refunded will be the same as the one of the original transaction.| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo refund ([MoTo Channel](androidobjects.md#moto-channel), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate an automatic refund +api.automaticRefund("00000000-0000-0000-0000-000000000000"); + +//Initiate an automatic refund using MoTo Options +MoToOptions moToOptions = new MoToOptions(); +moToOptions.setChannel(MoToChannel.TO); + +api.automaticRefund("00000000-0000-0000-0000-000000000000", moToOptions); +``` + +** Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry') +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Automatic Partial Refund + +`automaticRefund` + +A refund operation moves funds from the merchant account to the cardholder's credit card. This operation allows you to PARTIALLY refund a card automatically without requiring the cardholder to dip/tap/swipe his card. In its simplest form you only have to pass the amount, currency and the Original Transaction ID (GUID). Note that the amount can not go above the amount of the original sale. If a refund is attempted for an amount higher than the one of the original sale, the transaction will be automatically declined. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to refund - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the refund| +| `originalTransactionID` Required
*String* | Links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo refund ([MoTo Channel](androidobjects.md#moto-channel), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate an automatic partial refund for 5.00 Great British Pounds +api.automaticRefund(new BigInteger("500"),Currency.GBP,"00000000-0000-0000-0000-000000000000"); + +//Initiate an automatic partial refund for 5.00 Great British Pounds using MoTo Options +MoToOptions moToOptions = new MoToOptions(); +moToOptions.setChannel(MoToChannel.MO); + +api.automaticRefund(new BigInteger("500"),Currency.GBP,"00000000-0000-0000-0000-000000000000", moToOptions); +``` + +** Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry') +*** + + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Refund reversal{#6} + +`refundReversal` + +A refund reversal, also called refund VOID allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. In it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionID` Required
*String* | transaction id of the original refund| +| `options`
[*SaleOptions*](androidobjects.md#4) | An object to store all the customization options for the transaction.| + +**Code example** + +```java +//Initiate a refund reversal for 10.00 in Great British Pounds +api.refundReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000"); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**signatureRequired**](androideventlisteners.md#15) + +Invoked if card verification requires signature. +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## MoTo Sale{#7} + +`MoToSale` + +Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo sale ([MoTo Channel](androidobjects.md#moto-channel), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +//Initiate a MoTo sale for 10.00 in Great British Pounds +MoToOptions options = new MoToOptions(); +options.setCustomerReference("MoTo Sale Example"); + +api.motoSale(new BigInteger("1000"), Currency.EUR, options); + +//Initiate a MoTo sale for 10.00 USD using Money Remitance options +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("Test Integration", CountryCode.USA); +MoToOptions moToOptions = new MoToOptions(moneyRemittanceOptions); + +api.motoSale(new BigInteger("1000"), Currency.USD, moToOptions); + +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing'). + +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started.| + + + + +## MoTo Refund{#8} + +`moToRefund` + +A MOTO refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionId`
*String* | If present it links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo refund ([MoTo Channel](androidobjects.md#moto-channel), [Money Remittance Options](androidobjects.md#money-remittance-options),...)| + +**Code example** + +```java +MoToOptions options = new MoToOptions(); +options.setCustomerReference("MoTo Refund Example"); + +api.motoRefund(new BigInteger("1000"), Currency.EUR, "00000000-0000-0000-0000-000000000000",options); + + +//Initiate a MoTo refund for 10.00 USD using Money Remitance options +MoneyRemittanceOptions moneyRemittanceOptions = new MoneyRemittanceOptions("John Doe", CountryCode.USA); +MoToOptions moToOptions = new MoToOptions(moneyRemittanceOptions); + +api.motoRefund(new BigInteger("1000"), Currency.USD,"00000000-0000-0000-0000-000000000000", moToOptions); +``` +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing'). + +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started.| + + +## MoTo Reversal{#9} + +`moToReversal` + +A MOTO reversal, also called VOID allows the user to reverse a previous sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionId` Required
*String* | Id of the original sale transaction.| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo reversal.| + +**Code example** + +```java +MoToOptions options = new MoToOptions(); +options.setCustomerReference("MoTo Reversal Example"); + +api.motoReversal("00000000-0000-0000-0000-000000000000",options); +``` +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing'). + +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started.| + + +## MoTo Pre-Auth{#10} + +`motoPreauthorization` + +A MOTO pre-auth initiates a pre-authorization operation to the card reader. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `options`
[*MoToOptions*](androidobjects.md#moto-options) | An object to store optional parameters for a MoTo sale.| + +**Code example** + +```java +MoToOptions options = new MoToOptions(); +options.setCustomerReference("MoTo Sale Example"); + +api.motoPreauthorization(new BigInteger("1000"), Currency.EUR, options); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing'). + +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#OperationStartResult)*| Object containing information about the financial operation started.| + +## Signature result + +`signatureResult` + +A signatureRequired event is invoked during a transaction when a signature verification is required (f.ex when a payment is done with a swiped or chip and sign card). The merchant is required to ask the cardholder for signature and approve (or decline) the signature. signatureResult tells the card reader if the signature was approved by passing the value true in the method. To decline a signature event then false should be passed to the card reader. Note that this event is only required for an HiLite or Hi5 integration and can be safely ignored for a PAX or Telpo integration. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `accepted` Required
*Boolean* | pass true if merchant accepts cardholder signature| + +**Code example** + +```java +//Approves signature automatically in signatureRequired event +@Override +public void signatureRequired(SignatureRequest signatureRequest, Device device){ + api.signatureResult(true); +} +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +|*[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + + + + +## Tip Adjustment + +`TipAdjustment` + +A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled by the processor at the end of the day. +Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and VANTIV. + +Dependencies: +The code example provided depends on RxJava, take a look a their documentation to see how to easily include this dependency in your android project. If you do not want to use RxJava or any additional dependencies then AsyncTask, provided by android, can be used instead for this asynchronous processing. Still we recommend using RxJava as it improves readability and maintainability. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `tipAmount` Required
*BigDecimal* | Tip amount added to the original (base) transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*ENUM* | Currency of the original transaction | +| `originalTransactionID` Required
*String* | Unique id of the original sale transaction as received from the card reader (EFTTransactionID)| + +**Code example** + +```java +Observable.fromCallable(new Callable() { + @Override + public FinancialStatus call() throws Exception { + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + } +}) +.subscribeOn(Schedulers.io()) +.observeOn(AndroidSchedulers.mainThread()) +.subscribe(new Consumer() { + @Override + public void accept(@NonNull FinancialStatus status) throws Exception { + if (status == FinancialStatus.AUTHORISED) { + //SUCCESS + } else if (status == FinancialStatus.DECLINED) { + //DECLINED + } else { + //FAILED + } +}); +``` + +**Returns** + + +Result of the tip adjustment transaction, it returns a FinancialStatus, the possible values are : + +| Parameter | Notes | +| ----------- | ----------- | +| **FinancialStatus**| - **FinancialStatus.AUTHORISED** (tip adjustment approved by the processor)
- **FinancialStatus.FAILED** (system error or timeout)
- **FinancialStatus.DECLINED** (tip adjustment declined by the processor).| + +If two tip adjustments are sent for the same sale transaction, the second tip adjustment will override the first one. In case the transaction fails (not declined) we recommend that you prompt the user of the POS to retry the adjustment. + +## Tokenize Card{#12} + +`tokenizeCard` + +Returns a card token (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice) + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `options`
[*SaleOptions*](androidobjects.md#4) | An object to store all the customization options for the transaction.| + +**Code example** + +```java +//Tokenize a card +api.tokenizeCard(); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + +## Card PAN{#13} + +`cardPan` + +A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `options`
[*SaleOptions*](androidobjects.md#4) | An object to store all the customization options for the transaction.| + +**Code example** + +```java +//Gets the PAN of a card +api.cardPan(); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation started. Most specifically the `transactionReference` which **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.| + + + + +## Pre-Auth + +`preAuthorization` + +A pre-auth initiates a pre-authorization operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts tip configuration and a map with extra parameters. +A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to pre-auth - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `preauthOptions`
[*MerchantAuthOptions*](androidobjects.md#MerchantAuthOptions) | An object to store merchant authentication options for pre-auth operations.| + +**Code example** + +```java +//Initiate a pre-auth for 1.00 in Great British Pounds +api.preAuthorization(new BigInteger("100"),Currency.GBP); + +//With Options +MerchantAuthOptions preauthOptions = new MerchantAuthOptions(); +preauthOptions.setCustomerReference("CustomerReference"); + +api.preAuthorization(new BigInteger("100"),Currency.GBP, preauthOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + + +## Pre-Auth Increase/Decrease + +`preAuthorizationIncrease` + +This operation allows the merchant to increase/decrease the amount of a previously performed pre-auth operation. For example, if a tab was opened at a restaurant and the consumer is adding new orders going above the initial pre-authorized amount, it is required to increase the amount of the initial pre-authorization before capturing it. If the merchant wants to release part of a pre-auth, an increase with **negative** amount should be passed to the function. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of the pre-auth increase, in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionID` Required
*String* | Transaction ID of the original pre-auth operation| +| `preauthOptions`
[*Options*](androidobjects.md#7) | An object to store merchant authentication options for pre-auth operations.| + +**Code example** + +```java +//Initiate a pre-auth increase for 1.00 in Great British Pounds +Options preauthOptions = new Options(); +preauthOptions.setCustomerReference("CustomerReference"); + +api.preAuthorizationIncrease(new BigInteger("100"),Currency.GBP,"00000000-0000-0000-0000-000000000000", preauthOptions); + +//Initiate a pre-auth decrease for 1.00 in Great British Pounds +Options preauthOptions = new Options(); +preauthOptions.setCustomerReference("CustomerReference"); + +api.preAuthorizationIncrease(new BigInteger("-100"),Currency.GBP,"00000000-0000-0000-0000-000000000000", preauthOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + + +## Pre-Auth Capture + +`preAuthorizationCapture` + +A pre-authorized transaction can be captured to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank. + +**Please note that a pre-authorization can only be captured ONCE, multiple partial captures are not allowed**. If for some reason, the pre-authorization was captured for an incorrect amount, you can attempt to reverse the capture (does not work with all acquirers). If the capture reversal was declined, the cardholder needs to come back into the store with his card to get refunded or re-authorize the transaction. Alternatively, the cardholder can give his card details over the phone to the merchant and a MOTO pre-auth or MOTO refund can be issued. + +Card schemes set specific rules around which businesses are able to use pre-auth transactions. Eligibility is determined based on the Merchant Category Code (MCC), together with the card scheme. + +Card schemes have their own set of rules on authorisation expiry. Capturing a transaction after the scheme expiry time increases the risk of a failed capture, and may also increase the interchange and/or scheme fees charged for the transaction. Card schemes can also expire an authorisation before or after the official scheme expiry period has been reached. You can often capture a payment successfully after an authorisation has expired. Depending on the card scheme, there can be a fee for late capture, and an increase in interchange fee. The risk of cardholder chargebacks increase as well. + +| Scheme | MCC | +| ----------- | ----------- | +| Mastercard | All MCCs except 5542 | +| Visa | All MCCs except 5542 | +| Discover | 3351-3441, 3501-3999, 4111, 4112, 4121, 4131, 4411, 4457, 5499, 5812, 5813, 7011, 7033, 7996, 7394, 7512, 7513, 7519, 7999 | +| American Express | All MCCs except 5542 | + +**VISA rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 3501-3999, 7011 | Lodging | 31 days | 15% | +| 3351-3500, 7512 | Car Rental | 31 days | 15% | +| 4411 | Steamship and Cruise Lines | 31 days | 15% | +| 7513 | Truck Rentals | 7 days | 15% | +| 7033 | Trailer Parks and Campgrounds | 7 days | 15% | +| 7519 | Motor Home and Recreational Vehicle Rentals | 7 days | 15% | +| 5552 | Electric Vehicle Charging | 7 days | 15% | +| 7523 | Parking and Garages | 7 days | 15% | +| 7394 | Equipment, Tool, Furniture and Appliance Rental | 7 days | none | +| 7999 | Recreation Services | 7 days | none | +| 7996 | Amusement Parks, Carnivals, Circuses, Fortune Tellers | 7 days | none | +| 5599 | Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers | 7 days | none | +| 4457 | Boat Rentals and Leasing | 7 days | none | +| 5571 | Motorcycle Shops and Dealers | 7 days | none | +| 4111 | Local and Suburban Commuter, Passenger Transportation, including Ferries | 7 days | 25 USD (or equivalent amount in local currency) | +| 4112 | Passenger Railways | 7 days | 25 USD (or equivalent amount in local currency) | +| 4131 | Bus Lines | 7 days | 25 USD (or equivalent amount in local currency) | +| 5812 | Eating Places and Restaurants | Same day | 20% | +| 5813 | Drinking Places, Bars, Taverns, Cocktail Lounges, Nightclubs, Discotheques | Same day | 20% | +| 4121 | Taxicabs and Limousines (Card-Absent Environment only) | Same day | 20% | + +**MASTERCARD rules** + +| MCC | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- | +| All MCCs | 30 days | 20% | + +**Maestro rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 5812 | Eating Places and Restaurants | 7 days | 20% | +| 5814 | Fast Food Restaurants | 7 days | 20% | + + +**AMEX rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| All MCCs | 7 days | +Note: Pre-Auth with AMEX is only available in the United States/Canada with the processor TSYS. + + + +**Discover rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | 10 days | + +**Diners rules** + +| MCC | Debit/credit | Authorization timeframe | +| ----------- | ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | All | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Credit | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Debit | 7 days | + + +**JCB rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Hotel and Car rental | Time of stay/rental | +| All MCCs except Hotel and Car rental | 1 year | + + + + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to pre-auth - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](androidobjects.md#13) | Currency of the charge| +| `originalTransactionID` Required
*String* | Transaction id of the original pre-auth transaction| +| `preauthOptions`
[*Options*](androidobjects.md#7) | An object to store merchant authentication options for pre-auth operations.| + +**Code example** + +```java +//Initiate a pre-auth capture for 1.00 in Great British Pounds +Options preauthOptions = new Options(); +preauthOptions.setCustomerReference("CustomerReference"); + +api.preAuthorizationCapture(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000", preauthOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + +## Pre-Auth/Capture Reversal + +`preAuthorizationReversal` + +A Pre-Auth reversal allows the user to reverse a previous pre-auth operation. This operation reverts (if possible) a specific pre-auth identified with a transaction id. +A pre-authorized reversal transaction **will release the whole pre-authorized amount**, for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged. For partial releases, please check the [Pre-Auth Increase/Decrease](androidtransactions.md#pre-auth-increasedecrease) operation. + +A Pre-Auth reversal can be used to reverse a capture operation as well. A capture reversal transaction **will release all the funds withheld**. Reversing a capture operation can only be done before the funds are automatically settled at night, please note that not all acquirers support reversal of captured transactions. If a capture reversal is attempted after the funds have been moved, the operation will receive a decline.
When the capture is reverted it returns to the previous state ([CAPTURED](androidobjects.md#34) -> [AUTHORISED](androidobjects.md#34)). + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*String* |Transaction id of the original pre-auth or capture GUID transaction.| +| `preauthOptions`
[*Options*](androidobjects.md#7) | An object to store merchant authentication options for pre-auth operations.| + +**Code example** + +```java +//Initiate a pre-auth reversal +api.preAuthorizationReversal("00000000-0000-0000-0000-000000000000"); + +Options preauthOptions = new Options(); +preauthOptions.setCustomerReference("CustomerReference"); + +//Initiate a pre-auth reversal with options +api.preAuthorizationReversal("00000000-0000-0000-0000-000000000000", preauthOptions); +``` + +**Events invoked** + +[**currentTransactionStatus**](androideventlisteners.md#14) + +Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry'). +*** + +[**endOfTransaction**](androideventlisteners.md#16) + +Invoked when the terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](androidobjects.md#operation-start-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + + +## Standalone Tokenized Payments Operations (Tokenize and Modify) + +`standaloneTokenizedPaymentsOperations` + +### Standalone Tokenized Sale + +** Overview ** + +The **`tokenizedOperation`** functionality in the Handpoint Android SDK enables card tokenization followed by a sale transaction. It is executed through the `Hapi` Android interface. + +This operation consists of two stages: + +1. **Card Tokenization**: The SDK tokenizes the card and triggers the **`Events.CardTokenized` event**, providing the tokenized card details and control callbacks. +2. **Sale Execution**: The integrator must invoke the `resume()` method from the callback object to proceed with the sale transaction. The outcome is returned through the **`Events.EndOfTransaction` event**. + +--- + +** Method Signature ** + +```kotlin +/** + * Tokenized Operation on a specific device using regular parameters. + * This operation consists of two parts. The first part, performs a tokenization of the card, + * whose token is sent to the integrator through the Events.CardTokenized event. + * Once the integrator wishes to continue the operation, + * it must execute the resume method of the object sent through the event, + * with the data of the operation it wishes to perform. + * This operation will be executed and + * the result will be received through the Events.EndOfTransaction event. + * The operation supported is Sale. + * + * @param amount The transaction amount. + * @param currency The currency to be used. + * @param options An object containing configuration parameters for customer reference. + * @return True if the command was sent successfully to the device. False if sending failed. + */ +@JvmOverloads +fun tokenizedOperation(amount: BigInteger, currency: Currency, options: Options = Options()): OperationStartResult +``` + +--- + +** Events Flow ** + +*** 1. `Events.CardTokenized` *** + +Triggered after the card is tokenized. Provides: + +- **`CardTokenizationData`**: Contains tokenized card information. +- **`ResumeCallback`**: Allows the integrator to resume, cancel, or finish the operation. + +*** 2. `Events.EndOfTransaction` *** + +Triggered after the sale transaction is completed, returning the transaction result. + +--- + +** cardTokenized Event Components ** + +*** CardTokenizationData *** + +| Field | Type | Description | +|-----------------------|-------------------|--------------------------------------------------| +| `token` | `String` | Tokenized card value. | +| `expiryDate` | `String` | Card's expiry date. | +| `tenderType` | `TenderType` | Transaction type: `CREDIT`, `DEBIT`, or `NOT_SET`.| +| `issuerCountryCode` | `CountryCode` | Country code of the issuer (defaults to `Unknown`).| +| `cardBrand` | `String` | Brand of the card (e.g., Visa, MasterCard). | +| `languagePref` | `String` | Preferred language setting. | +| `tipAmount` | `BigInteger` | Tip amount (defaults to `BigInteger.ZERO`). | + +--- + +*** ResumeCallback *** + +Interface responsible for managing the continuation or termination of the tokenization operation. + +| Method | Description | Exceptions | +|--------------------------------------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `fun resume(operationDto: OperationDto)` | Continues the operation with a specified `OperationDto`. Only `Sale` operations are allowed. | `ResumedOperation`, `CancelledOperation`, `TimeoutOperation`, `IllegalStateException` | +| `fun finishWithoutCardOperation()` | Completes the operation without proceeding to a card transaction. | `ResumedOperation`, `CancelledOperation`, `TimeoutOperation`, `IllegalStateException` | +| `fun cancel()` | Cancels the ongoing operation. | `ResumedOperation`, `CancelledOperation`, `TimeoutOperation`, `IllegalStateException` | + +> **Note:** +> Calling any method multiple times, after timeout, or after cancellation triggers exceptions. + +--- + +*** Example Handling of `Events.CardTokenized` (Kotlin) *** + +```kotlin +override fun onCardTokenized( + cardTokenizationData: CardTokenizationData, + resumeCallback: ResumeCallback +) { + // Access tokenized card details + val token = cardTokenizationData.token + val cardBrand = cardTokenizationData.cardBrand + + // Decide next action: proceed with sale + resumeCallback.resume( + OperationDto.Sale( + amount = BigInteger.valueOf(2000), + currency = Currency.getInstance("USD"), + options = SaleOptions(/* configuration options */) + ) + ) +} +``` + +--- + +** OperationDto ** + +A sealed class representing supported transaction types after tokenization. + +| Subclass | Fields | Description | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| `Sale` | `amount: BigInteger`, `currency: Currency`, `options: SaleOptions` | Initiates a sale transaction. | +| `Refund` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String?`, `options: RefundOptions` | Initiates a refund transaction. *(Not allowed after tokenization)* | +| `SaleReversal` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String`, `options: SaleReversalOptions` | Reverses a previous sale. *(Not allowed after tokenization)* | +| `RefundReversal` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String`, `options: RefundReversalOptions` | Reverses a previous refund. *(Not allowed after tokenization)* | + +--- + +** Behavior and Restrictions ** + +- **Only `Sale` operations are allowed** when invoking `resume()` after receiving the `cardTokenized` event. + - Passing other operation types (`Refund`, `SaleReversal`, `RefundReversal`) will result in a transaction result with **`MessageType.FEATURE_NOT_SUPPORTED`**. + +- Proper exception handling is required when using the `ResumeCallback` methods. + +--- + +** Exceptions ** + +| Exception | Description | +|------------------------|--------------------------------------------------------------------------------| +| `ResumedOperation` | Thrown if the operation was already resumed. | +| `CancelledOperation` | Thrown if the operation was previously cancelled. | +| `TimeoutOperation` | Thrown if the operation timed out. | +| `IllegalStateException` | Thrown for any invalid operation state. | + +--- + +** Sequence Diagram ** + +[](/img/standalone_tokenized_SALE.png) +--- + +** Summary ** + +The **`tokenizedOperation`** method securely tokenizes card data and passes control to the integrator via the **`Events.CardTokenized` event**, delivering: + +1. **`CardTokenizationData`**: Contains the tokenized card details. +2. **`ResumeCallback`**: Allows integrators to resume with a supported `Sale` operation, cancel, or finish without a transaction. + +The result of the operation is returned through the **`Events.EndOfTransaction` event**. + +> **Tip:** Always validate and handle exceptions when interacting with `ResumeCallback` to ensure smooth operation flow. + +--- + +### Standalone Tokenized Refund, Reversal and RefundReversal + +`standaloneTokenizedRefund` + +** Overview ** + +The **`tokenizedOperation`** functionality in the Handpoint Android SDK allows the execution of a card tokenization followed immediately by a specified operation (such as SaleReversal, Refund, or RefundReversal). + +In this version, the integrator provides the required operation as a parameter, and the SDK performs: + +1. Card Tokenization (with a REST API request to retrieve the card token). +2. Execution of the operation passed by the integrator. + +The result of both actions is delivered through the **`Events.EndOfTransaction` event**. + +--- + +** Method Signature ** + +```kotlin +/** + * Tokenized Operation on a specific device using regular parameters. + * This operation consists of the consecutive execution of two operations: + * Tokenization of the card and the operation passed by parameter by + * the integrator. The result of both operations will be received through + * the Events.EndOfTransaction event. + * The operations supported are: SaleReversal, Refund, RefundReversal + * + * @param currency The currency to be used. + * @param operation The operation to be executed. + * @param options An object containing configuration parameters for customer reference. + * @return True if the command was sent successfully to the device. False if the sending was not successful. + */ +fun tokenizedOperation( + currency: Currency, + operation: OperationDto, + options: Options = Options() +): OperationStartResult +``` + +--- + +** Events Flow ** + +*** Events.EndOfTransaction *** + +Triggered after both card tokenization and the specified operation are executed. The integrator receives the final transaction result in this event. + +--- + +** Supported Operations ** + +This version of `tokenizedOperation` supports the following **OperationDto** types: + +| OperationDto Subclass | Fields | Description | +|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| `Refund` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String?`, `options: RefundOptions` | Initiates a refund transaction. | +| `SaleReversal` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String`, `options: SaleReversalOptions` | Reverses a previous sale. | +| `RefundReversal` | `amount: BigInteger`, `currency: Currency`, `originalTransactionID: String`, `options: RefundReversalOptions` | Reverses a previous refund. | + +> **Note:** +> `Sale` operation is **not supported** in this version of `tokenizedOperation`. + +--- + +** Tokenization Process ** + +Internally, the SDK performs a REST API call to retrieve the card token. Once retrieved, it immediately proceeds to execute the operation provided by the integrator. + +--- + +*** Example Usage (Kotlin) *** + +```kotlin +val refundOperation = OperationDto.Refund( + amount = BigInteger.valueOf(1500), + currency = Currency.getInstance("EUR"), + originalTransactionID = "TX123456", + options = RefundOptions(/* options */) +) + +val result = hapi.tokenizedOperation( + currency = Currency.getInstance("EUR"), + operation = refundOperation, + options = Options(/* config */) +) +``` + +--- + +** Behavior and Restrictions ** + +- The SDK will **automatically execute** both: + 1. Tokenization (via REST API). + 2. The provided operation (`Refund`, `SaleReversal`, or `RefundReversal`). + +- The integrator will receive the outcome via **`Events.EndOfTransaction`**. + +- Sale operations are **not allowed** in this mode. + +--- + +** Exceptions ** + +The method itself returns `false` if the command fails to send to the device. Other exceptions related to transaction processing will be communicated via the **`Events.EndOfTransaction`** event. + +--- + +** Sequence Diagram ** + +[](/img/standalone_Tokenized_Refund_and_reversals.png) + +--- + +** Summary ** + +The **`tokenizedOperation`** method allows integrators to provide a specific operation upfront (Refund, SaleReversal, RefundReversal). The SDK: + +1. Retrieves the card token via REST API. +2. Immediately executes the operation. +3. Returns the result via **`Events.EndOfTransaction`**. + +> **Tip:** Use this method when you want to perform tokenization and the operation in one streamlined flow, without intermediate decision points. + +--- + +## Cloud Tokenized Payments Operations + +`cloudTokenizedPaymentsOperations` + +** Overview ** + +In Cloud mode, integrators can control the Android SDK via one of our Cloud clients, which are our [REST API](/restapi/restintroduction), [JavaScript SDK](/javascript/javascriptintroduction) and [Windows SDK](/windows/windowsintroduction). + +There are two possible types of Cloud integrations: + +- **Integration with a callback URL** +- **Integration with Polling** + +--- + +**Integration with a callback URL** + +If a `callbackUrl` and a `token` are included in the request, the terminal sends a POST with the transaction result to the specified URL. The token will be included in the HTTP header as `AUTH-TOKEN` and can be used on the callback URL side to identify or authenticate the call. + +***Example:*** + +*Request:* + +```bash +curl -X POST -H"ApiKeyCloud: XXXXXXX-KXDMZV1-HW8MXBG-XXXXXXX" -H"Content-Type: application/json" \ +-d '{"operation": "sale", "terminal_type":"PAXA910S", "serial_number": "2840011110", "amount": "1034", "currency": "EUR", "tokenize": true, "callbackUrl": "https://results.example.com/callback", "token": "auth-token-1" }' \ +https://cloud.handpoint.io/transactions +``` +*Response:* +```json +{"statusMessage":"Operation Accepted"} +``` + +*Callback:* + +The following is an example of the transaction result sent to the specified `callbackUrl`: +```json +{ + "accountType": "", + "aid": "A0000000041010", + "arc": "0000", + "authorisationCode": "010119", + "balance": null, + "budgetNumber": "", + "cardEntryType": "ICC", + "cardHolderName": "", + "cardLanguagePreference": "", + "cardSchemeName": "VISA", + "cardToken": "535120cMXnuK6046", + "cardTypeId": "************6046", + "chipTransactionReport": "", + "currency": "EUR", + "customData": "...", + "customerReceipt": "https://receipts.handpoint.io/receipts/f6059a10-c1fe-11ef-9cf2-8b8a2cdbabca/customer.html", + "customerReference": "", + "deviceStatus": { + "applicationName": "Atom", + "applicationVersion": "20.4.9.2-RC.5", + "batteryCharging": "Full", + "batteryStatus": "100", + "batterymV": "8154", + "bluetoothName": "PAXA910S", + "externalPower": "USB", + "serialNumber": "2840011110", + "statusMessage": "" + }, + "dueAmount": 0, + "errorMessage": "", + "expiryDateMMYY": "0129", + "finStatus": "AUTHORISED", + "iad": "0210A04003240000000000000000000000FF", + "issuerResponseCode": "00", + "maskedCardNumber": "************6046", + "merchantAddress": "Random Street, Some City", + "merchantName": "Random Merchant", + "merchantReceipt": "https://receipts.handpoint.io/receipts/f6059a10-c1fe-11ef-9cf2-8b8a2cdbabca/merchant.html", + "metadata": null, + "mid": "12S001", + "moneyRemittanceOptions": null, + "multiLanguageErrorMessages": {}, + "multiLanguageStatusMessages": { + "en_CA": "Approved or completed successfully", + "fr_FR": "Transaction approuvée" + }, + "originalEFTTransactionID": "", + "paymentScenario": "CHIPCONTACTLESS", + "requestedAmount": 524, + "rrn": "513815902180", + "signatureUrl": "", + "statusMessage": "Approved or completed successfully", + "tenderType": "CREDIT", + "tid": "123123", + "tipAmount": 0, + "totalAmount": 524, + "transactionID": "16059a10-c1fe-11ef-9cf2-8b8a2cdbabca", + "transactionOrigin": "CLOUD", + "transactionReference": "b45ff306-78f2-4d3b-970c-e47c8d9b9f83", + "tsi": "0000", + "tvr": "0000008001", + "type": "SALE", + "unMaskedPan": "", + "verificationMethod": "NOT_REQUIRED", + "efttimestamp": 1735048275000, + "efttransactionID": "16059a10-c1fe-11ef-9cf2-8b8a2cdbabca", + "tipPercentage": 0.0, + "recoveredTransaction": false +} +``` + +**Integration using Polling** + +If the request does not include a `callbackUrl` and a `token`, then polling can be used to retrieve the transaction result from Handpoint's transaction-result endpoint. + +***Example:*** + +*Request:* + +```bash +curl -X POST -H"ApiKeyCloud: XXXXXXX-KXDMZV1-HW8MXBG-XXXXXXX" -H"Content-Type: application/json" \ +-d '{"operation": "sale", "terminal_type":"PAXA910S", "serial_number": "2840011110", "amount": "1034", "currency": "EUR", "tokenize": true }' \ +https://cloud.handpoint.io/transactions +``` + +*Response:* + +Using the `transactionResultId`, integrators can poll the transaction-result endpoint to retrieve the result: + +```json +{ + "statusMessage": "Operation Accepted", + "transactionResultId": "1840011114-1735048331833" +} +``` + +*Polling request:* + +```bash +curl -i -X GET -H"ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" -H"Content-Type: application/json" \ +https://cloud.handpoint.io/transaction-result/1840011114-1735048331833 +``` + +*Possible responses from polling:* + +- 204: Transaction still in process. +- 200: Transaction result is available. + + +--- + +### Cloud Tokenized Sale + +**Overview** + +The **Cloud Tokenized Operation** enables remote-triggered financial operations, where a cloud-based system initiates a request to tokenize a card and perform a **Sale** transaction using the Android SDK. + +This operation is initiated by sending a **`CloudFinancialRequest`** object. The SDK handles the following workflow: + +1. Parses and validates the `CloudFinancialRequest`. +2. Tokenizes the card (if `tokenize` is `true` and `operation` is `Sale`). +3. Triggers the **`Events.CardTokenized`** event with token and callback. +4. Proceeds with the Sale operation upon `resume()` call. +5. Emits the final result via **`Events.EndOfTransaction`**. + +--- + +**CloudFinancialRequest** + +**Description** + +A data object that represents the request payload for initiating cloud-based financial operations including tokenized sales. + +**Key Fields** + +| Field | Type | Description | +|--------------------------|-----------------------------------|-------------| +| `operation` | `Operations` | Must be set to `Operations.Sale` for this flow. | +| `tokenize` | `Boolean` | Must be set to `true` to trigger card tokenization. | +| `amount` | `String?` | Transaction amount as string. | +| `currency` | `String?` | Currency code. | +| `callbackUrl` | `String?` | If present, indicates REST API request. | +| `originalTransactionId` | `String` | Identifier of original transaction (if any). | +| `uuid` | `String` | Event UUID, auto-formatted as 6-digit string. | +| `transactionReference` | `String` | Reference for idempotency; auto-generated if blank. | +| `receipt` | `String?` | Raw or URL-based receipt data. | +| `metadata` | `Metadata?` | Optional metadata for the operation. | +| `merchantAuth` | `MerchantAuth?` | Merchant authentication object. | +| `duplicateCheck` | `Boolean` | Enables duplicate request validation. | +| `duplicateCheckEndpoint`| `String` | Optional custom endpoint for duplicate checks. | + +> **Note:** Other fields may be present but are not required for the tokenized Sale flow. + +--- + +**Internal Behavior** + +- The SDK uses `getParsedAmount()` and `getParsedCurrency()` to convert string values into typed `BigInteger` and `Currency`. +- If `callbackUrl` is present, the request is treated as a REST API request. +- If `tokenize` is `true` and `operation == Sale`, the card is tokenized, and the **`Events.CardTokenized`** event is emitted. +- After receiving the `resume()` call, the SDK performs the Sale operation. + +--- + +**Events Flow** + +1. `Events.CardTokenized` + +Emitted after card tokenization. Provides: +- `CardTokenizationData`: Includes card token and card info. +- `ResumeCallback`: To resume with the `Sale` operation. + +2. `Events.EndOfTransaction` + +Emitted after the sale is completed. + +--- + +**Behavior and Restrictions** + +- The only supported operation for this flow is **Sale**. +- Must set: + - `operation = Operations.Sale` + - `tokenize = true` +- Invoking `resume()` with any operation other than `Sale` will result in `MessageType.FEATURE_NOT_SUPPORTED`. + +--- + +**Example CloudFinancialRequest JSON** + +```json +{ + "operation": "Sale", + "tokenize": true, + "amount": "1000", + "currency": "EUR", + "transactionReference": "a1b2c3d4", + "callbackUrl": "https://merchant.com/callback" +} +``` + +--- + +**Example Kotlin Flow** + +```kotlin +override fun onCardTokenized( + cardTokenizationData: CardTokenizationData, + resumeCallback: ResumeCallback +) { + val sale = OperationDto.Sale( + amount = cardTokenizationData.tipAmount, + currency = Currency.getInstance("EUR"), + options = SaleOptions(/* additional config */) + ) + resumeCallback.resume(sale) +} +``` + +--- + +**Sequence Diagram** + +[](/img/cloud_tokenized_Sale.png) + +--- + +**Summary** + +The **Cloud Tokenized Operation** enables external services to initiate tokenized Sale transactions through a structured `CloudFinancialRequest`. The SDK handles card tokenization and executes the Sale transaction if the correct flags are set. + +> **Tip:** This is ideal for headless or server-triggered flows that require secure card tokenization and transaction execution in a single interaction. + + +### Cloud Tokenized Sale Reversal + +**Overview** + +The **Sale Reversal Tokenized Operation** is a cloud-initiated process that tokenizes a card and performs a **Sale Reversal** transaction. This operation is triggered via a `CloudFinancialRequest` object and follows the same interaction pattern as other dependant tokenized operations. + +It is identified by: + +- `operation = Operations.SaleReversal` +- `tokenize = true` + +Upon receiving this request, the SDK emits the **`Events.DependantReversalReceived`** event. The integrator is then responsible for controlling the transaction flow using the `ResumeDependantOperationExecutor` interface. + +--- + +**CloudFinancialRequest Configuration** + +**Required Fields** + +| Field | Value | Description | +|------------------|----------------------------------|---------------------------------------------| +| `operation` | `Operations.SaleReversal` | Identifies a Sale Reversal request. | +| `tokenize` | `true` | Triggers tokenization before the operation. | + +Other fields such as `originalTransactionId`, `currency`, `amount`, and `transactionReference` must also be set as needed. + +--- + +**Event: `Events.DependantReversalReceived`** + +Emitted when the SDK receives a cloud request for a **Sale Reversal** with tokenization enabled. The integrator handles this event via the `DependantOperationEvent` interface: + +```kotlin +interface DependantOperationEvent { + fun dependantRefundReceived( + amount: BigInteger, + currency: Currency, + originalTransactionId: String, + resumeDependantOperation: ResumeDependantOperation + ) + + fun dependantReversalReceived( + originalTransactionId: String, + resumeDependantOperation: ResumeDependantOperation + ) +} +``` + +--- + +**Interface: ResumeDependantOperationExecutor** + +```kotlin +interface ResumeDependantOperationExecutor { + fun executeDependantOperation(amount: BigInteger, currency: Currency, originalTransactionId: String) + fun finishWithoutCardOperation() + fun cancel() +} +``` + +--- + +**Implementation: ResumeDependantSaleReversalExecutorImpl** + +```kotlin +class ResumeDependantSaleReversalExecutorImpl( + private val currency: Currency, + private val originalTransactionId: String, + private val options: InternalSaleReversalOptions, + private val delegate: Hapi +): ResumeDependantOperationExecutor { + + override fun executeDependantOperation(amount: BigInteger, currency: Currency, originalTransactionId: String) { + val refundOperationDto = OperationDto.SaleReversal( + amount, + currency, + originalTransactionId, + options + ) + val result = delegate.tokenizedOperation(currency, refundOperationDto, options).operationStarted + if (!result) { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.FAILED + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + sendTransactionResult(transactionResult) + } + } + + override fun finishWithoutCardOperation() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.AUTHORISED + transactionResult.type = TransactionType.VOID_SALE + transactionResult.currency = currency + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.transactionID = UUID.randomUUID().toString() + transactionResult.eFTTransactionID = transactionResult.transactionID + transactionResult.originalEFTTransactionID = originalTransactionId + + InstancesManager.cardReader.isCardPresent = true + sendTransactionResult(transactionResult) + } + + override fun cancel() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.CANCELLED + transactionResult.type = TransactionType.VOID_SALE + transactionResult.currency = Currency.Unknown + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.originalEFTTransactionID = originalTransactionId + sendTransactionResult(transactionResult) + } + + internal fun sendTransactionResult(transactionResult: TransactionResult) { + TransactionResultHandler.transactionFinished(transactionResult) + } +} +``` + +--- + +**Behavior and Flow** + +| Method | Description | +|----------------------------------|-------------| +| `executeDependantOperation(...)` | Executes the `SaleReversal` operation after tokenization. | +| `finishWithoutCardOperation()` | Returns an `AUTHORISED` transaction result without financial movement. | +| `cancel()` | Sends a `CANCELLED` transaction result indicating cancellation. | + +--- + +**Sequence Diagram** + +[](/img/cloud_tokenized_SaleReversal.png) +--- + +**Summary** + +The **Sale Reversal Tokenized Operation** is a secure, cloud-triggered flow for performing a **Sale Reversal** using a tokenized card. The operation is handled through the `DependantReversalReceived` event and executed with a `ResumeDependantOperationExecutor` implementation. + +> **Tip:** Use `finishWithoutCardOperation()` when the sale reversal is already completed outside the SDK but you want to report it as authorised for consistency. + + +### Cloud Tokenized Refund + +**Overview** + +The **Refund Tokenized Operation** is a cloud-based flow that allows merchants to initiate a tokenized refund from a remote system. It uses the same `CloudFinancialRequest` object as other cloud operations. + +This operation is identified by: +- `operation = Operations.Refund` +- `tokenize = true` + +Upon receiving the request, the SDK emits the **`Events.DependantRefundReceived`** event. The integrator must handle this event by using the **`ResumeDependantOperationExecutor`** interface to define the next step. + +--- + +**CloudFinancialRequest Configuration** + +**Required Fields** + +| Field | Value | Description | +|------------------|------------------------------|-----------------------------------------| +| `operation` | `Operations.Refund` | Indicates the refund operation. | +| `tokenize` | `true` | Enables card tokenization. | + +Other standard fields such as `amount`, `currency`, `originalTransactionId`, and `transactionReference` should be populated according to the use case. + +--- + +**Event: `Events.DependantRefundReceived`** + +Triggered when a tokenized refund request is received from the cloud. The integrator must respond using a `ResumeDependantOperationExecutor` implementation. + +--- + +**Interface: ResumeDependantOperationExecutor** + +Defines the actions the integrator must take after receiving the refund request. + +```kotlin +interface ResumeDependantOperationExecutor { + + fun executeDependantOperation( + amount: BigInteger, + currency: Currency, + originalTransactionId: String + ) + + fun finishWithoutCardOperation() + + fun cancel() +} +``` + +--- + +**Implementation: ResumeDependantRefundExecutorImpl** + +This implementation manages the refund operation execution and fallback flows. + +```kotlin +class ResumeDependantRefundExecutorImpl( + private val currency: Currency, + private val options: InternalRefundOptions, + private val originalTransactionId: String, + private val delegate: Hapi +) : ResumeDependantOperationExecutor { + + override fun executeDependantOperation(amount: BigInteger, currency: Currency, originalTransactionId: String) { + val refundOperationDto = OperationDto.Refund( + amount, + currency, + originalTransactionId.ifBlank { null }, + options + ) + val result = delegate.tokenizedOperation(currency, refundOperationDto, options).operationStarted + if (!result) { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.FAILED + sendTransactionResult(transactionResult) + } + } + + override fun finishWithoutCardOperation() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.originalEFTTransactionID = originalTransactionId + transactionResult.finStatus = FinancialStatus.AUTHORISED + transactionResult.type = TransactionType.REFUND + transactionResult.currency = currency + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.transactionID = UUID.randomUUID().toString() + transactionResult.eFTTransactionID = transactionResult.transactionID + InstancesManager.cardReader.isCardPresent = true + sendTransactionResult(transactionResult) + } + + override fun cancel() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.CANCELLED + transactionResult.type = TransactionType.REFUND + transactionResult.currency = currency + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.originalEFTTransactionID = originalTransactionId + sendTransactionResult(transactionResult) + } + + internal fun sendTransactionResult(transactionResult: TransactionResult) { + TransactionResultHandler.transactionFinished(transactionResult) + } +} +``` + +--- + +**Behavior and Flow** + +| Method | Description | +|----------------------------------|-------------| +| `executeDependantOperation(...)` | Triggers the refund transaction using the provided amount, currency, and original transaction ID. | +| `finishWithoutCardOperation()` | Sends a transaction result with `AUTHORISED` status but **without processing a refund** — used when the refund was completed outside the SDK. | +| `cancel()` | Sends a transaction result with `CANCELLED` status — used when the integrator cancels the operation. | + +--- + +**Sequence Diagram** + +[](/img/cloud_tokenized_Refund.png) + +--- + +**Summary** + +The **Refund Tokenized Operation** is a controlled cloud-based refund workflow that tokenizes the card and delegates control to the integrator for determining the refund outcome. + +- Triggered via `CloudFinancialRequest` with `operation = Refund` and `tokenize = true`. +- Uses the `ResumeDependantOperationExecutor` interface to define the refund behavior. +- Provides flexibility to execute, authorize without refund, or cancel the transaction. + +> **Tip:** Use `finishWithoutCardOperation()` when refund logic is handled outside the SDK and you only need to notify the POS system. + + +### Cloud Tokenized Refund Reversal + +**Overview** + +The **Refund Reversal Tokenized Operation** is a cloud-triggered operation that securely tokenizes a card and performs a **Refund Reversal**. This operation is initiated via a `CloudFinancialRequest` object with: + +- `operation = Operations.RefundReversal` +- `tokenize = true` + +After receiving the request, the SDK emits the **`Events.DependantReversalReceived`** event. The integrator must respond by using the **`ResumeDependantOperationExecutor`** interface to control how the operation proceeds. + +--- + +**CloudFinancialRequest Configuration** + +**Required Fields** + +| Field | Value | Description | +|------------------|-----------------------------------|----------------------------------------------| +| `operation` | `Operations.RefundReversal` | Indicates the refund reversal operation. | +| `tokenize` | `true` | Enables card tokenization. | + +Other standard fields such as `amount`, `currency`, `originalTransactionId`, and `transactionReference` should also be included. + +--- + +**Event: `Events.DependantReversalReceived`** + +This event is emitted after receiving a valid cloud request for a refund reversal. The integrator must implement `ResumeDependantOperationExecutor` to define the next action. + +--- + +**Interface: ResumeDependantOperationExecutor** + +```kotlin +interface ResumeDependantOperationExecutor { + + fun executeDependantOperation( + amount: BigInteger, + currency: Currency, + originalTransactionId: String + ) + + fun finishWithoutCardOperation() + + fun cancel() +} +``` + +--- + +**Implementation: ResumeDependantRefundReversalExecutorImpl** + +```kotlin +class ResumeDependantRefundReversalExecutorImpl( + private val currency: Currency, + private val originalTransactionId: String, + private val options: InternalRefundReversalOptions, + private val delegate: Hapi +): ResumeDependantOperationExecutor { + + override fun executeDependantOperation(amount: BigInteger, currency: Currency, originalTransactionId: String) { + val refundOperationDto = OperationDto.RefundReversal( + amount, + currency, + originalTransactionId, + options + ) + val result = delegate.tokenizedOperation(currency, refundOperationDto, options).operationStarted + if (!result) { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.FAILED + sendTransactionResult(transactionResult) + } + } + + override fun finishWithoutCardOperation() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.AUTHORISED + transactionResult.type = TransactionType.VOID_REFUND + transactionResult.currency = currency + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.transactionID = UUID.randomUUID().toString() + transactionResult.eFTTransactionID = transactionResult.transactionID + transactionResult.originalEFTTransactionID = originalTransactionId + + InstancesManager.cardReader.isCardPresent = true + sendTransactionResult(transactionResult) + } + + override fun cancel() { + val transactionResult = InstancesManager.transactionData.generateTransactionResultWithoutResponse() + transactionResult.finStatus = FinancialStatus.CANCELLED + transactionResult.type = TransactionType.VOID_REFUND + transactionResult.currency = Currency.Unknown + transactionResult.totalAmount = BigInteger.ZERO + transactionResult.transactionOrigin = TransactionOrigin.CLOUD + transactionResult.originalEFTTransactionID = originalTransactionId + sendTransactionResult(transactionResult) + } + + internal fun sendTransactionResult(transactionResult: TransactionResult) { + TransactionResultHandler.transactionFinished(transactionResult) + } +} +``` + +--- + +**Behavior and Flow** + +| Method | Description | +|----------------------------------|-------------| +| `executeDependantOperation(...)` | Launches the `RefundReversal` operation after tokenization. | +| `finishWithoutCardOperation()` | Sends an `AUTHORISED` transaction result without moving funds — used when reversal is handled externally. | +| `cancel()` | Sends a `CANCELLED` result indicating the integrator aborted the operation. | + +--- + +**Sequence Diagram** + +[](/img/cloud_tokenized_refund_Reversal.png) + +--- + +**Summary** + +The **Refund Reversal Tokenized Operation** is a cloud-driven flow designed to securely tokenize a card and optionally reverse a refund. It follows the same interaction pattern as other dependant cloud operations, with three possible paths controlled by the integrator: + +- Execute the refund reversal. +- Acknowledge the transaction without refund movement. +- Cancel the operation entirely. + +> **Tip:** Use this operation in cloud or headless setups where refunds need to be securely reversed with authorization logging. diff --git a/android_versioned_sidebars/version-Android SDK 7.1010.7-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.7-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.7-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/android_versions.json b/android_versions.json index 6106d32..3761e1e 100644 --- a/android_versions.json +++ b/android_versions.json @@ -1,4 +1,5 @@ [ + "Android SDK 7.1010.7", "Android SDK 7.1010.6", "Android SDK 7.1010.5", "Android SDK 7.1010.3", diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptintroduction.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptintroduction.md new file mode 100644 index 0000000..3b63fd1 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptintroduction.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 1 +id: javascriptintroduction +--- + + + +# Introduction {#javascriptIntro} + +
+
+
+
+
+
+
+ JavaScript SDK
+
+
+ 
+
+
+
+
+
+ + +Download the Handpoint JavaScript SDK to integrate leading smartpos terminals with your cloud based software. The Handpoint JavaScript SDK is a simple javascript interface running in your web application which acts as a bridge between **the web browser and the payment terminal**, while shielding your software from handling card data. It is seamless to integrate, keeps your software out of PCI scope, and allows you to use the best Android terminals on the market. + +Complete your integration in just three steps, initialize the interface, choose a terminal and start a sale. It is as simple as it sounds. The only thing you need is a valid API key to communicate with the payment terminal. As part of the initialize step you will get back a list of terminals with which you can connect. Simply execute the financial operation, and within seconds you’ll get back the transaction result and receipt in your software, all while you monitor the transaction status. The Handpoint Javascript SDK seamlessly starts and manages the entire point to point encrypted transaction with the payment terminal, minimizing hassle for you and maximizing reliability, security, and control. + +For your merchants, the terminal setup is easier than a standalone. A merchant connects the terminal to their network, just like a smartphone, authenticates his/her account, and it simply works. Your software then control the terminal from anywhere in the world, and your merchants have secure, reliable and intuitive payments. + +## API Overview + +The following transaction flow shows how easy it is to add card present payments to your web based application. The interaction between your cloud application and the Handpoint Javascript SDK is simple and streamlined. The Handpoint Javascript SDK takes care of the communication with the payment terminal. The status messages are received in your web application via the callback function defined in the financial operation requests call. That’s it. + + + diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptobjects.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptobjects.md new file mode 100644 index 0000000..bd8432b --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptobjects.md @@ -0,0 +1,758 @@ +--- +sidebar_position: 8 +id: javascriptobjects +--- + + +# Objects + +## Acquirer{#21} + +`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** + +| 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** + +```json +"balance": { + "amount": 1000, + "currency": "EUR", + "negative": false, + "positive": true + } +``` + +## Bypass Options{#19} + +`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.| + +**Code example** + +```json +{ + "bypassOptions": { + "signatureBypass": true, + "pinBypass": true + } +} +``` + +## Card Entry Type{#29} + +`CardEntryType` Enum + +An enum representing different card entry types. + +**Possible values** + +`UNDEFINED` `MSR` `ICC` `CNP` + + +## Card Scheme Name{#30} + +`CardSchemeName` Enum + +An enum representing different card brands. + +**Possible values** + +`MasterCard` `Visa` `Maestro` `American Express` `Discover` `JCB` `Diners` `UnionPay` `Interac` + + +## Currency{#31} + +`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{#20} + +`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** + +```json +{ + "merchant_id_alpha": "Test_Merchant", + "serial_number": "614004878", + "ssk": "74817EA5C63437ADE7AA3A5401", + "terminal_type": "PAXA920", + "device_name": "0821032395-PAXA920" +} +``` + +## Device Status{#27} + +`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** + +```json +{ + "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{#33} + +`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: + +| Parameter | Notes | +| ----------- | ----------- | +| `UNDEFINED` (NOT FOUND)
| Any financial status other than the below mentioned financial statuses will be `UNDEFINED`. The `UNDEFINED` (NOT FOUND) status can be returned as a response to the [get transaction status](javascriptterminalmanagement.md#17) 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](javascriptterminalmanagement.md#17) 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](javascriptterminalmanagement.md#17) 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](javascripttransactiontypes.md#pre-auth-capture) 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](javascriptterminalmanagement.md#17) method. + + +## Merchant Auth{#17} + +`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[]*](#28) | Array of credentials.| + +**Code example** + +```json +{ + "merchantAuth": [{ + "acquirer": "ACQ_DUMMY", + "mid": "1111", + "tid": "2222", + "mcc": "3333", + "externalId": "4444" + }] +} +``` + +## Merchant Auth Credential{#28} + +`Credential` Object + +An object to store credentials (Acquirer, Mid, Tid, MCC and ExternalId) for merchant authentication. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `acquirer`
[*Acquirer*](#21) | 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** + +```json +{ + "acquirer": "ACQ_DUMMY", + "mid": "1111", + "tid": "2222", + "mcc": "3333" +} + +{ + "externalId": "4444" +} +``` + +## Merchant Auth Options{#25} + +`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*](#17) | Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).| + +**Code example** + +```json +{ + "customerReference": "MyCustomReference", + "merchantAuth": [ + { + "acquirer": "ACQUIRER", + "mid": "11111", + "tid": "22222", + "mcc": "33333" + } + ], +} +``` + +## Metadata{#metadata} + +`Metadata` Object + +An object to store metadata. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `metadata1`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata2`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata3`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata4`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata5`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| + +**Code example** + +```json +{ + "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** + +| Property | Description | +| ----------- | ----------- | +| `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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3))| + + +```json +{ + "moneyRemittanceOptions":{ + "fullName":"John Doe", + "countryCode":"USA" + } +} +``` + + + +## Operation Start Result + +`OperationStartResult` Object + +Object containing information about the financial operation being performed. + +**Properties** + +| Parameter | Description | +| ----------- | ----------- | +| `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](javascriptobjects.md#18) object. | + + +## Options{#26} + +`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| +| `metadata`
[*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** + +```json +{ + "customerReference": "MyCustomReference", + "metadata": { + "metadata1": "data1", + "metadata2": "data2", + "metadata3": "data3", + "metadata4": "data4", + "metadata5": "data5" + } +} +``` + +## Payment Scenario{#34} + +`PaymentScenario` Enum + +An enum representing different types of payment scenario. + +**Possible values** + +`UNKNOWN` `MAGSTRIPE` `MAGSTRIPECONTACTLESS` `CHIP` `CHIPCONTACTLESS` `CHIPFAILMAGSTRIPE` `MOTO` + + +## Refund Options{#24} + +`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.| +| `tokenize`
*Boolean* | Used to enable tokenization in the payments flow. See [Android SDK 7.1009.5](/android/androidreleasenotes#710095) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature.| +| `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*](#19) | Configuration required to bypass the pin or signature verification methods.| +| `merchantAuth`
[*MerchantAuth*](#17) | Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).| +| `metadata`
[*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*](javascriptobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + +**Code example** + +```json +{ + "customerReference": "MyCustomReference", + "tokenize": false, + "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{#23} + +`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.| +| `tokenize`
*Boolean* | Used to enable the tokenization flow in Tokenized Payments Operationss. See [Android SDK 7.1009.5](/android/androidreleasenotes#710095) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information.| +| `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*](#39) | Configuration for the tipping menu of the payment terminal.| +| `bypassOptions`
[*BypassOptions*](#19) | Configuration required to bypass the pin or signature verification methods.| +| `merchantAuth`
[*MerchantAuth*](#17) | Configuration required to fund a specific merchant account in a multi-mid scenario (one payment terminal funding multiple merchants).| +| `metadata`
[*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*](javascriptobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + +**Code example** + +```json +{ + "customerReference": "MyCustomReference", + "tokenize": false, + "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{#38} + +`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** + +| Property | Description | +| ----------- | ----------- | +| `cancelAllowed`
*bool* | A `boolean` allowing the user to know if the payment terminal will accept a cancel request.| +| `status`
[*status*](#38) | A `status` enum representing the status of the transaction.| +| `message`
*String* | A `string` containing the status message of the transaction.| +| `deviceStatus`
[*Device Status*](#27) | A `DeviceStatus` object containing information about the payment terminal.| + + +## Tender Type{#35} + +`TenderType` Enum + +An enum representing different tender types. + +**Possible values** + +`NOT_SET` `CREDIT` `DEBIT` + + +## Tip Configuration{#39} + +`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
*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** + +```json +{ + baseAmount: '2000', + tipPercentages: [5,10,15,20,25], + enterAmountEnabled: true, + skipEnabled: false, + footer: 'Thank you!!! ;)' +} +``` +## Transaction Result Object{#18} + +`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) | Balance available on the card| +| `batchNumber`
*String * | If available from the acquirer, the batch number where this transaction has been included| +| `budgetNumber`
*String * | Used to split payments over a period of months| +| `cardEntryType`
[*CardEntryType*](#29) | Method used by the terminal to read the card| +| `cardLanguagePreference`
*String * | Preferred language of the card (EMV tag 5F2D)| +| `cardSchemeName`
[*CardSchemeName*](#30) | 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*](#31) | 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*](#27) | 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*](#33) | 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*](#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*](#34) | 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*](#35) | 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*](#36) | 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*](#37) | 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** + +```json +{ + "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{#22} + +`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*](#27) | 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*](#38) | An enum containing information about the status of the transaction.| + + +## Transaction Type{#36} + +`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{#37} + +`VerificationMethod` Enum + +An enum representing different cardholder verification methods. + +**Possible values** + +`UNDEFINED` `SIGNATURE` `PIN` `PIN_SIGNATURE` `FAILED` `NOT_REQUIRED` `MOBILE_PASS_CODE` + + + diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptprocessingpayments.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptprocessingpayments.md new file mode 100644 index 0000000..e12bddd --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptprocessingpayments.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 3 +id: javascriptprocessingpayments +--- + + +# Trigger Amounts + +Your test payments are sent against a test server on the Handpoint side which simulates the behavior of an acquiring bank. Funds are not moved and sensitive data from the card is fully encrypted. You can use trigger amounts to generate some specific responses from our servers: + +**Sale amounts** + +| Amount | Behaviour | +| ----------- | ----------- | +| 37.79 | Issuer response code = 01 (Refer to issuer) | +| 37.84 | Issuer response code = 05 (Not authorized) | +| 37.93 | Issuer response code = 04 (Pick up card) | +| 37.57 | Request is partially approved | +| 37.68 | Request timeout | + +:::tip +Supporting partial approval is **mandatory** for the US market. Partial authorization occurs when a payment card authorization is attempted for a transaction and there are not enough funds available in the account to cover the full amount. The issuer returns an authorization for the amount available in the account, leaving you to obtain an additional form of payment from the customer for the balance. +::: \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptquickintegration.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptquickintegration.md new file mode 100644 index 0000000..f5c935d --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptquickintegration.md @@ -0,0 +1,112 @@ +--- +sidebar_position: 4 +id: javascriptquickintegration +--- + + + +# Integration Guide + +:::tip +Pre-requisite: request your test credentials (API key) and test payment terminal from Handpoint. +::: + +The following example shows how you can integrate your web application with the Handpoint javascript SDK to perform a sale transaction in four easy steps: + +1) Download the [handpoint.js](javascriptintroduction.md#javascriptIntro) SDK. + +2) In the same directory, copy both handpoint.js and the code below in an html file. + +3) In the code below, replace the variable apiKey with your test api key and replace the variable deviceName with the concatenation of your terminal serial number and model, for example **0821032395-PAXA920**. + + Note: If your payment terminal shows the debug watermark on the screen when it is on, then keep the variable `environmentIsDevelopment` to true otherwise change it to false. + +4) Open the HTML file in the browser and see the test transaction immediately. + +**SIMPLE, FAST, and EASY** + +```html + + + + +
*string* | The API key provided by Handpoint for the merchant.| +| `dev_or_prod_environment` Required
*boolean* | Value which defines if the JS SDK is targeting the development environment (true -> cloud.handpoint.io) or the production environment (false -> cloud.handpoint.com).| +| `recovery_EoT_callback` Required
*promise* |Promise collecting the pending transaction results which couldn't be delivered to the web application during the execution of the transaction, for example if the network connection became unstable. The callback input parameter is a TransactionResult object. When the promise is resolved the JS SDK will send the ACK to the payment terminal to mark the result as recovered and the device will delete it from its storage. If the promise is rejected, the device will resend the TransactionResult until the promise is correctly resolved and the ACK sent to the payment terminal. The sdk has a 5 second window for the promise to be resolved | + +**Code example** + +```javascript +Handpoint.init('API KEY', true, (pendingEoT) => { + console.log('Recovered Transaction -> ' + JSON.stringify(pendingEoT); + return handleTransactionResultPromise(pendingEoT); +}) + +// For simple or sync operations you may return a resolved Promise. +Handpoint.init('API KEY', true, (pendingEoT) => { + console.log('Recovered Transaction -> ' + JSON.stringify(pendingEoT); + return Promise.resolve(); +}) +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Devices**| List of device objects.| + + +## Connect{#2} + +`Connect` Method + +Connects the Javascript SDK to a payment terminal. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device_name` Required
*string* | The target payment terminal to connect to. The device_name is returned in the Device object of the initialize call.| + +**Code example** + +```javascript +Handpoint.connect('0821330373-PAXA920'); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Connection Result**|**200** code for OK
**403** code for NOK| + + +## Disconnect{#3} + +`Disconnect` Method + +Disconnects the Javascript SDK from a payment terminal. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device_name` Required
*string* | The target payment terminal to disconnect from. The device_name is returned in the Device object of the initialize call.| + +**Code example** + +```javascript +Handpoint.connect('1850345672-PAXA920PRO'); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Connection Result**|`Disconnected` message for OK
`ERROR disconnecting` message for NOK| + + +## Stop Listening Device{#7} + +`StopListeningDevice` Method + +This operation stops the connection between your application and the payment terminal. It stops listening to transaction events and resets the connection with the card reader. + + +**Code example** + +```javascript +//Stop Listening to Events +Handpoint.stopListeningDevice(); +``` +## Stop Current Transaction{#13} + +`StopCurrentTransaction` Method + +Operation used to stop the current transaction. The transaction can only be stopped at specific stages of payment processing, for example a transaction can not be stopped when the card is being read but can be stopped when waiting for the cardholder to initially insert a card. + + +**Code example** + +```javascript +Handpoint.stopCurrentTransaction(); + +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Promise Successful Response**|`{finStatus: CANCELLED, statusMessage: 'Operation stopped'}`| +| **Promise Error Response**|`{finStatus: FAILED, errorMessage: 'Unable to stop current transaction'}`| +| **Promise Error Response**|`{ finStatus: FAILED, errorMessage: 'No response received from the card reader' }`| + + +## Print Receipt{#14} + +`PrintReceipt` Method + +Print on demand functionality allowing the merchant to print any HTML formatted receipt. It is possible to print images or barcodes as well as passing directly a URL to the printReceipt function. A bitmap can also be printed, in order to do so it needs to be rendered as an image and inserted into the html. + +:::tip +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. +::: + + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `receipt` Required
*string* | HTML receipt or url to locate the receipt, it can be found in the response of a financial operation, in the fields merchantReceipt or customerReceipt. The receipt must match the following [HTML Print Format](https://handpoint.atlassian.net/wiki/spaces/PD/pages/1409875969/Html+Print+Format).| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + + +**Code example** + +```javascript +Handpoint.printReceipt('https://location_of_receipt_container.com/receipt_location', CallbackFunction(stat){...}); + +var htmlReceipt = '[...] HTML receipt [...]' + +Handpoint.printReceipt(htmlReceipt, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Print Receipt Response**|A specific status object which describes the printing action (PrinterOutOfPaper, ErrorConnectingToPrinter or ReceiptPrintSuccess)| + + +## Ping Device{#15} + +`PingDevice` Method + +This operation will ping the terminal to confirm if it is online. The promise is correctly resolved if the device is online and successfully answers to the ping + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + + +**Code example** + +```javascript +Handpoint.pingDevice(CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Device Status**|A [*Device Status*](javascriptobjects.md#27) object.| + +## Update{#16} + +`Update` Method + +Triggers a terminal software and config update. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +Handpoint.update(CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Update Response**|A financial response object.| + + + +## Get Transaction Status{#17} + +`getTransactionStatus` Method + +If for any reasons you do not know if a transaction was approved or declined then this method will allow you to retrieve the status of the transaction from the Handpoint gateway. The `getTransactionStatus` method is a convenient way to retrieve the current status of a transaction based on its unique reference. This method accepts a `transactionReference` as a parameter and returns the current status of the transaction. The `transactionReference` is returned at the start of a transaction, as part of the [Operation Start Result](javascriptobjects.md#operation-start-result) object. + + +The main [*FinancialStatus*](javascriptobjects.md#33) that can be returned as a response to this method are the following ones: + +- AUTHORISED - Transaction was successful. +- DECLINED - Transaction was declined. +- UNDEFINED (NOT FOUND) - 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. +- IN_PROGRESS - The transaction has been received by the gateway but the outcome is not known yet, try again after a few seconds. +- REFUNDED - Transaction was refunded. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `transactionReference` Required
*String* | The `transactionReference` ([UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))) is returned at the start of a transaction, as part of the [Operation Start Result](javascriptobjects.md#operation-start-result) object.| + +**Code example** + +```javascript +Handpoint.getTransactionStatus(transactionReference).then( + transactionResult => { + console.log('Transaction Result -> ' + JSON.stringify(transactionResult)) + } +).catch( + errorStatus => console.log('ERROR in getTransactionStatus -> ' + JSON.stringify(errorStatus)) +); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Transaction Status**| A [*Transaction Result*](javascriptobjects.md#18) object, indicating the status of the requested transaction.| \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascripttransactiontypes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascripttransactiontypes.md new file mode 100644 index 0000000..928fddc --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascripttransactiontypes.md @@ -0,0 +1,779 @@ +--- +sidebar_position: 6 +id: javascripttransactiontypes +--- + +# Transaction Types + +## Sale{#4} + +`Sale` Method + +A sale initiates a transaction with the payment terminal. In its simplest form, you only have to pass the amount and currency as parameters. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `saleOptions`
[*SaleOptions*](javascriptobjects.md#23) | An object to store the customization options for a sale ([Tip Configuration](javascriptobjects.md#39), [Metadata](javascriptobjects.md#metadata), [Money Remittance Options](javascriptobjects.md#money-remittance-options),...). This object can be empty if no options are required.| +| `callback_function ` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var saleOptions = { + 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" + } + ], + metadata: { + metadata1: "data1", + metadata2: "data2", + metadata3: "data3", + metadata4: "data4", + metadata5: "data5" + }, + moneyRemittanceOptions:{ + fullName:"John Doe", + countryCode:"USA" + } +} + +let operationStartedResult = handpoint.sale('1000', 'USD', saleOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + + +## Sale And Tokenization{#5} + +`SaleAndTokenization` Method + +A sale operation which also returns a card token. This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `saleOptions` Required
[*SaleOptions*](javascriptobjects.md#23) | An object to store the customization options for a sale and tokenize ([Metadata](javascriptobjects.md#metadata), [Money Remittance Options](javascriptobjects.md#money-remittance-options),...). This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var saleOptions = { + 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" + } + ], + moneyRemittanceOptions:{ + fullName:"John Doe", + countryCode:"USA" + } +} + +let operationStartedResult = handpoint.saleAndTokenization('1000', 'USD', saleOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## Transaction Recovery{#6} + +`StartRecovery` Method + +The terminal has a transaction recovery loop to automatically send back the pending [*Transaction Result*](javascriptobjects.md#18) to the web application in case it becomes unreachable (network issue or other). + +For the first 100 seconds after a transaction is completed, a background thread will attempt to deliver the result every 5 seconds. If the web application is still unreachable after the first 100 seconds, the retry loop turns into an exponential increment to the power of 2 (8s-16s-32s etc…). + +The recovery loop is reinitialized every time the Handpoint application is restarted on the payment terminal or the startRecovery method is triggered.The [*Transaction Result*](javascriptobjects.md#18) received through the transaction recovery loop will have the recoveredTransaction field set to true. + +**Important information: The web application must be successfully connected to a terminal in order to receive the pending transactions.** + +**Code example** + +```javascript +//Start recovery of pending transactions +Handpoint.startRecovery(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Promise Successful Response**|The event has been sent to the payment terminal.| +| **Promise Error Response**|The event was not sent to the payment terminal because it is unreachable.| + + +## Sale Reversal{#8} + +`SaleReversal` Method + +A sale Reversal, also called sale VOID allows the merchant to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. In its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `originalTransactionID` Required
*string* | The transaction id of the original sale authorization.| +| `merchantAuthOptions`
[*MerchantAuthOptions*](javascriptobjects.md#25) | An object to store the customization options for a saleReversal operation. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var saleReversalOptions = { + customerReference: "MyCustomReference", + merchantAuth: [ + { + acquirer: "ACQUIRER", + mid: "11111", + tid: "22222", + mcc: "33333" + } + ], +} + +let operationStartedResult = handpoint.saleReversal('1000', 'USD', 'OriginalSaleGUID', saleReversalOptions, CallbackFunction(stat){...}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## Refund{#9} + +`Refund` Method + +A refund initiates a transaction with the payment terminal. This operation moves funds from the merchant account to the cardholder´s credit card. In its simplest form, you only have to pass the amount and currency as parameters. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `originalTransactionID`
*string* | The transaction id of the original sale authorization.| +| `refundOptions`
[*RefundOptions*](javascriptobjects.md#24) | An object to store the customization options for a refund ([Metadata](javascriptobjects.md#metadata), [Money Remittance Options](javascriptobjects.md#money-remittance-options),...). This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var refundOptions = { + customerReference: "MyCustomReference", + bypassOptions: { + signatureBypass: true, + pinBypass: true + }, + merchantAuth: [ + { + acquirer: "ACQUIRER", + mid: "11111", + tid: "22222", + mcc: "33333" + } + ], + moneyRemittanceOptions:{ + fullName:"John Doe", + countryCode:"USA" + } +} + +let operationStartedResult = handpoint.refund('1000', 'USD', undefined ,refundOptions, CallbackFunction(stat){...}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult + +// Linked Refund +handpoint.refund('1000', 'USD', 'OriginalSaleGUID' ,refundOptions, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## Refund Reversal{#10} + +`RefundReversal` Method + +A Refund Reversal, also called Refund VOID, allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. In its simplest form, you only have to pass the amount, currency and originalTransactionID as parameters. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `originalTransactionID` Required
*string* | The transaction id of the original refund authorization.| +| `merchantAuthOptions`
[*MerchantAuthOptions*](javascriptobjects.md#25) | An object to store the customization options for a refundReversal operation. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var refundReversalOptions = { + customerReference: "MyCustomReference", + merchantAuth: [ + { + acquirer: "ACQUIRER", + mid: "11111", + tid: "22222", + mcc: "33333" + } + ], +} + +let operationStartedResult = handpoint.refundReversal('1000', 'USD', 'OriginalRefundGUID', refundReversalOptions, CallbackFunction(stat){...}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## MoTo Sale + +`moToSale` Method + +Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `saleOptions`
[*SaleOptions*](javascriptobjects.md#23) | An object to store the customization options for a MOTO sale (Customer reference, [Money Remittance Options](javascriptobjects.md#money-remittance-options),...). This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var saleOptions = { + customerReference: "MyCustomReference", + moneyRemittanceOptions:{ + fullName:"John Doe", + countryCode:"USA" + } + } + +let operationStartedResult = handpoint.moToSale('1000', 'USD', saleOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + + +## MoTo Refund + +`moToRefund` Method + +A MOTO refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `originalTransactionID`
*string* | If this field is populated, it links the refund with a previous sale and effectively limits the maximum amount refunded to that of the original transaction.| +| `refundOptions`
[*RefundOptions*](javascriptobjects.md#24) | An object to store the customization options for a refund (Customer reference, [Money Remittance Options](javascriptobjects.md#money-remittance-options),...). This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var refundOptions = { + customerReference: "MyCustomReference", + moneyRemittanceOptions:{ + fullName:"John Doe", + countryCode:"USA" + } +} + +let operationStartedResult = handpoint.moToRefund('1000', 'USD', undefined ,refundOptions, CallbackFunction(stat){...}); + +// Linked Refund +Handpoint.moToRefund('1000', 'USD', '00000000-0000-0000-0000-000000000000' ,refundOptions, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## MoTo Reversal + +`moToReversal` Method + +A MOTO reversal, also called VOID allows the user to reverse a previous MOTO sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*string* |The transaction id of the original sale or refund authorization.| +| `options`
[*Options*](javascriptobjects.md#26) | An object to store the customization options for a MOTO reversal operation. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var moToReversalOptions = { + customerReference: "MyCustomReference" +} + +let operationStartedResult = handpoint.moToReversal('00000000-0000-0000-0000-000000000000', moToReversalOptions, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + + +## MoTo Pre-Auth + +`moToPreAuthorization` Method + +A MOTO pre-auth initiates a pre-authorization operation to the card reader. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*integer* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*string* | Currency of the transaction.| +| `options`
[*Options*](javascriptobjects.md#26) | An object to store the customization options for a MOTO sale. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var saleOptions = { + customerReference: "MyCustomReference", + } + +let operationStartedResult = handpoint.moToPreAuthorization('1000', 'USD', saleOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +let transactionReference = operationStartedResult.transactionReference +let result = await operationStartedResult.transactionResult +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartedResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Specifically the `transactionReference` and the `transactionResult` (promise).| + + +## Tip Adjustment + +`TipAdjustment` + +A tip adjustment operation allows merchants to adjust the tip amount of a sale or a pre-auth capture transaction before the batch of transactions is settled by the processor at the end of the day. Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and WORLDPAY/VANTIV. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `tipAmount` Required
*BigInteger* |Tip amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `originalTransactionID` Required
*String* |Transaction id of the original transaction| + +**Code example** + +```javascript +handpoint.tipAdjustment('100', '00000000-0000-0000-0000-000000000000') { +}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Status Message**| `Tip adjusted` message for OK
`ERROR` message for NOK| + + + +## Tokenize Card{#11} + +`TokenizeCard` Method + +Returns a card token (representing the card number). This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `options`
[*Options*](javascriptobjects.md#26) | An object to store the customization options for a tokenizeCard operation. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var options = { + customerReference: "MyCustomReference", +} + +Handpoint.tokenizeCard(options, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Tokenize Card Response**|[*Transaction Result Object*](javascriptobjects.md#18)| + + +## Card Pan{#12} + +`CardPan` Method + +A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `options`
[*Options*](javascriptobjects.md#26) | An object to store the customization options for a cardPan operation. This object can be empty if no options are required.| +| `callback_function` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +var options = { + customerReference: "MyCustomReference", +} + +Handpoint.tokenizeCard(options, CallbackFunction(stat){...}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **Card Pan Response**|[*Transaction Result Object*](javascriptobjects.md#18)| + + +## Pre-Auth + + +`preAuthorization` + +A pre-auth initiates a pre-authorization operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts tip configuration and a map with extra parameters. + +A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to be pre-authorized - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*Currency* | Currency of the pre-auth| +| `preauthOptions`
[*SaleOptions*](javascriptobjects.md#23) | An object to store the customization options for a pre-auth. This object can be empty if no options are required.| +| `callback_function ` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +// Perform the PreAuth operation +let operationStartedResult = handpoint.preAuthorization('1234', 'EUR', preauthOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +``` + +## Pre-Auth Increase/Decrease + +`preAuthorizationIncrease` + +This operation allows the merchant to increase/decrease the amount of a previously performed pre-auth operation. For example, if a tab was opened at a restaurant and the consumer is adding new orders going above the initial pre-authorized amount, it is required to increase the amount of the initial pre-authorization before capturing it. If the merchant wants to release part of a pre-auth, an increase with **negative** amount should be passed to the function. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to be pre-authorized - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*Currency* | Currency of the charge| +| `originalTransactionID` Required
*String* | Transaction ID of the original pre-auth operation| +| `preauthOptions`
*Options* | An object to store merchant authentication options for pre-auth operations.| +| `callback_function ` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +// Perform the PreAuth Increase operation +let operationStartedResult = handpoint.preAuthorizationIncrease('1234', 'EUR','00000000-0000-0000-0000-000000000000', preauthOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); + +// Perform the PreAuth Decrease operation +let operationStartedResult = handpoint.preAuthorizationIncrease('-1234', 'EUR','00000000-0000-0000-0000-000000000000', preauthOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + + +## Pre-Auth Capture + +`preAuthorizationCapture` + +A pre-authorized transaction can be captured to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank. + +**Please note that a pre-authorization can only be captured ONCE, multiple partial captures are not allowed**. If for some reason, the pre-authorization was captured for an incorrect amount, you can attempt to reverse the capture (does not work with all acquirers). If the capture reversal was declined, the cardholder needs to come back into the store with his card to get refunded or re-authorize the transaction. Alternatively, the cardholder can give his card details over the phone to the merchant and a MOTO pre-auth or MOTO refund can be issued. + +Card schemes set specific rules around which businesses are able to use pre-auth transactions. Eligibility is determined based on the Merchant Category Code (MCC), together with the card scheme. + +Card schemes have their own set of rules on authorisation expiry. Capturing a transaction after the scheme expiry time increases the risk of a failed capture, and may also increase the interchange and/or scheme fees charged for the transaction. Card schemes can also expire an authorisation before or after the official scheme expiry period has been reached. You can often capture a payment successfully after an authorisation has expired. Depending on the card scheme, there can be a fee for late capture, and an increase in interchange fee. The risk of cardholder chargebacks increase as well. + + +| Scheme | MCC | +| ----------- | ----------- | +| Mastercard | All MCCs except 5542 | +| Visa | All MCCs except 5542 | +| Discover | 3351-3441, 3501-3999, 4111, 4112, 4121, 4131, 4411, 4457, 5499, 5812, 5813, 7011, 7033, 7996, 7394, 7512, 7513, 7519, 7999 | +| American Express | All MCCs except 5542 | + +**VISA rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 3501-3999, 7011 | Lodging | 31 days | 15% | +| 3351-3500, 7512 | Car Rental | 31 days | 15% | +| 4411 | Steamship and Cruise Lines | 31 days | 15% | +| 7513 | Truck Rentals | 7 days | 15% | +| 7033 | Trailer Parks and Campgrounds | 7 days | 15% | +| 7519 | Motor Home and Recreational Vehicle Rentals | 7 days | 15% | +| 5552 | Electric Vehicle Charging | 7 days | 15% | +| 7523 | Parking and Garages | 7 days | 15% | +| 7394 | Equipment, Tool, Furniture and Appliance Rental | 7 days | none | +| 7999 | Recreation Services | 7 days | none | +| 7996 | Amusement Parks, Carnivals, Circuses, Fortune Tellers | 7 days | none | +| 5599 | Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers | 7 days | none | +| 4457 | Boat Rentals and Leasing | 7 days | none | +| 5571 | Motorcycle Shops and Dealers | 7 days | none | +| 4111 | Local and Suburban Commuter, Passenger Transportation, including Ferries | 7 days | 25 USD (or equivalent amount in local currency) | +| 4112 | Passenger Railways | 7 days | 25 USD (or equivalent amount in local currency) | +| 4131 | Bus Lines | 7 days | 25 USD (or equivalent amount in local currency) | +| 5812 | Eating Places and Restaurants | Same day | 20% | +| 5813 | Drinking Places, Bars, Taverns, Cocktail Lounges, Nightclubs, Discotheques | Same day | 20% | +| 4121 | Taxicabs and Limousines (Card-Absent Environment only) | Same day | 20% | + +**MASTERCARD rules** + +| MCC | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- | +| All MCCs | 30 days | 20% | + +**Maestro rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 5812 | Eating Places and Restaurants | 7 days | 20% | +| 5814 | Fast Food Restaurants | 7 days | 20% | + + +**AMEX rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| All MCCs | 7 days | +Note: Pre-Auth with AMEX is only available in the United States/Canada with the processor TSYS. + + +**Discover rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | 10 days | + +**Diners rules** + +| MCC | Debit/credit | Authorization timeframe | +| ----------- | ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | All | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Credit | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Debit | 7 days | + + +**JCB rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Hotel and Car rental | Time of stay/rental | +| All MCCs except Hotel and Car rental | 1 year | + + + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Amount of funds to be pre-authorized - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*Currency* | Currency of the pre-auth| +| `originalTransactionID` Required
*String* | Transaction ID of the original pre-auth operation| +| `preauthOptions`
*Options* | An object to store merchant authentication options for pre-auth operations.| +| `callback_function ` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +// Perform the PreAuth Capture operation +let operationStartedResult = handpoint.preAuthorizationCapture('1234', 'EUR','00000000-0000-0000-0000-000000000000', preauthOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| + +## Pre-Auth/Capture Reversal + +`preAuthorizationReversal` + +A Pre-Auth reversal allows the user to reverse a previous pre-auth operation. This operation reverts (if possible) a specific pre-auth identified with a transaction id. +A pre-authorized reversal transaction **will release the whole pre-authorized amount**, for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged. For partial releases, please check the [Pre-Auth Increase/Decrease](javascripttransactiontypes.md#pre-auth-increasedecrease) operation. + +A Pre-Auth reversal can be used to reverse a capture operation as well. A capture reversal transaction **will release all the funds withheld**. Reversing a capture operation can only be done before the funds are automatically settled at night, please note that not all acquirers support reversal of captured transactions. If a capture reversal is attempted after the funds have been moved, the operation will receive a decline.
When the capture is reverted it returns to the previous state ([CAPTURED](javascriptobjects.md#33) -> [AUTHORISED](javascriptobjects.md#33)). + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*String* |Transaction id of the original pre-auth transaction| +| `preauthOptions`
*Options* | An object to store merchant authentication options for pre-auth operations.| +| `callback_function ` Required
*string* | Callback function to subscribe to the transaction status updates.| + +**Code example** + +```javascript +// Perform the PreAuth Reversal operation +let operationStartedResult = handpoint.preAuthorizationReversal('00000000-0000-0000-0000-000000000000', preauthOptions, function (stat) { + console.log('Transaction status received -> '+ stat.message) +}); +``` + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](javascriptobjects.md#operation-started-result)*| Object containing information about the financial operation performed. Most specifically the `transactionReference` which **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.| diff --git a/javascript_versioned_sidebars/version-JavaScript SDK 7.2.4-sidebars.json b/javascript_versioned_sidebars/version-JavaScript SDK 7.2.4-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/javascript_versioned_sidebars/version-JavaScript SDK 7.2.4-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/javascript_versions.json b/javascript_versions.json index 3c4fb77..4a9a8b1 100644 --- a/javascript_versions.json +++ b/javascript_versions.json @@ -1,4 +1,5 @@ [ + "JavaScript SDK 7.2.4", "JavaScript SDK 7.2.3", "JavaScript SDK 7.2.2", "JavaScript SDK 7.2.0", diff --git a/restapi/restobjects.md b/restapi/restobjects.md index 8579f4b..c6942dd 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -661,7 +661,7 @@ An object to store information about the request sent to the payment terminal. ```` -## Transaction Result Object +## Transaction Result Object {#transactionResult} `TransactionResult` Object @@ -682,6 +682,7 @@ An object holding information about the result of a transaction. | `arc`
*String * | EMV Authorisation Response Code (EMV tag 8A)| | `authorisationCode`
*String * | Acquirer response code| | `balance`
[*Balance*](#balance) | Balance available on the card| +| `batchNumber`
*String * | If available from the acquirer, the batch number where this transaction has been included| | `budgetNumber`
*String * | Used to split payments over a period of months| | `cardEntryType`
[*CardEntryType*](#cardEntryType) | Method used by the terminal to read the card| | `cardLanguagePreference`
*String * | Preferred language of the card (EMV tag 5F2D)| diff --git a/restapi/restreleasenotes.md b/restapi/restreleasenotes.md index 01faf55..5b1b534 100644 --- a/restapi/restreleasenotes.md +++ b/restapi/restreleasenotes.md @@ -9,6 +9,11 @@ id: restreleasenotes Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: +## 2.23.1 +**Features:** + +The batch number is returned in the Transaction Result object now as `batchNumber`, provided the acquirer returns it. Please see [Transaction Result Object](restobjects.md#transactionResult) + ## 2.23.0 **Bug fixes:** diff --git a/restapi_versioned_docs/version-REST API 2.23.1/assets/postmanCollection.png b/restapi_versioned_docs/version-REST API 2.23.1/assets/postmanCollection.png new file mode 100644 index 0000000..ec43e6e Binary files /dev/null and b/restapi_versioned_docs/version-REST API 2.23.1/assets/postmanCollection.png differ diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restdownloads.md b/restapi_versioned_docs/version-REST API 2.23.1/restdownloads.md new file mode 100644 index 0000000..653b02c --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restdownloads.md @@ -0,0 +1,10 @@ +--- +sidebar_position: 4 +id: restapidownloads +--- + +# POSTMAN Collection + +Below is a Postman collection to get started with the REST API integration. In this collection you will find examples of different [operations](restobjects#operation-types-description) such as initialize, ping device, sale, sale (money remittance example), MOTO sale, sale and tokenize, sale reversal, sale with partial approval, refund, linked refund, refund reversal, print receipt(Bitmap and custom receipt), tokenize card, update terminal, tip-adjustment, Pre-Auth, MOTO Pre-Auth, [GetTransactionResult](restendpoints.md#transaction-resulttransactionresultid) and [GetTransactionStatus](restendpoints.md#transactionstransactionreferencestatus). + +[Download this Postman Collection](/files/API_REST_Nov2023.postman_collection.json.zip) diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restendpoints.md b/restapi_versioned_docs/version-REST API 2.23.1/restendpoints.md new file mode 100644 index 0000000..163cdf3 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restendpoints.md @@ -0,0 +1,746 @@ +--- +sidebar_position: 6 +id: restendpoints +--- + + + +# REST API Endpoints + + +## /initialize + + + +`Initialize` + +Initializes the REST API client and returns the list of payment terminals associated with the merchant account. We recommend that you display the list of available payment terminals to the merchant in your software. Each API key is unique per merchant and needs to be configurable in your backend. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | + + +Returns + + +| Devices | +| ----------- | +| List of [Device](restobjects.md#deviceObject) object. | + + +**Code Example** + + +```shell +Operation executed using CLI tool CURL: + +REQUEST: + curl -X GET \ + -H "ApiKeyCLoud: MeRcHaNt-ApIkEy" \ + "https://cloud.handpoint.com/initialize" (production) + "https://cloud.handpoint.io/initialize" (development) + +RESPONSE: + Code 200 -> Body: + [ + { + "merchant_id_alpha": "merchantID", + "serial_number": "082104578", + "ssk": "A1B2C3D4E5F60718293A4B5C6D7E8F901A2B3C4D5E6F7890ABCDEF0123456789", + "terminal_type": "PAXA920" + } + ] +``` + +:::tip +Reminder that SSK (Shared Secret Key) is a value unique to a Merchant, and the same Merchant (SSK) can have assigned multiple devices from different manufacturers. This includes PAX and Datecs (eg. HiLite) +::: + + + +## /transactions + + + +`Transactions` + +POST endpoint used to send a financial operation to the payment terminal. The transaction type to be executed (sale, refund etc.) is defined in the `operation` field of the request body. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Request Body: Transaction Request` Required
[TransactionRequest](restobjects.md#transactionRequest) | Object containing the transaction request information. | + + +**Returns** + + +| Response | Response Code | +| ----------- | ----------- | +| **Transaction Accepted** | The response code 202 is received from the API if the transaction was successfully sent to the payment terminal. | +| **BadRequest DeviceIsBusy Error** | The response code 400 with error 1001 is received from the API if the payment terminal is already processing a transaction. | +| **BadRequest DeviceNotResponding Error** | The response code 400 with error 1002 is received from the API if the payment terminal is offline. | +| **BadRequest CancelOperationNotAllowed Error** | The response code 400 with error 1003 is received from the API if the stopCurrentTransaction operation cannot be executed. A transaction can only be cancelled at specific steps of the transaction, while waiting for the card to be inserted or on PIN screen. | + +**Code Example** + +:::tip +Make sure that your transactionReference is unique per request, and change it for every new request attempt (even if the request contains the same values re-attempt). This will improve logs and could help troubleshooting. +::: + +```shell +Operation executed using CLI tool CURL: +REQUEST: + curl -X POST \\ + -H"ApiKeyCLoud: MeRcHaNt-ApIkEy" \\ + -H"Content-Type: application/json" \\ +Transaction Request without callbackUrl and token + -d '{ + "operation":"sale", + "amount":"10000", + "currency":"EUR", + "terminal_type":"PAXA920", + "serial_number":"1547854757", + "customerReference":"op15248", + "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f" + }' \\ +Transaction Request with callbackUrl and token + -d '{ + "operation":"sale", + "amount":"10000", + "currency":"EUR", + "terminal_type":"PAXA920", + "serial_number":"1547854757", + "customerReference":"op15248", + "callbackUrl":"https://url.where.the.result.is.served.com", + "token":"123456789", + "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f" + }' \\ + "https://cloud.handpoint.com/transactions" (production) + "https://cloud.handpoint.io/transactions" (development) + +RESPONSES: + Code 202 +Transaction Request without callbackUrl + { + "transactionResultId": "0821032398-1628774190395", + "statusMessage": "Operation Accepted", + "transactionReference":"00000000-0000-0000-0000-000000000000" + } + +Transaction Request with callbackUrl and token + { + "statusMessage": "Operation Accepted", + "transactionReference":"00000000-0000-0000-0000-000000000000" + } + + Code 400 Ex:DeviceIsBusy + { + "error": { + "statusCode": 400, + "name":"BadRequestError", + "message": { + "error": 1001, + "message":"The device is busy" + } + } + } +``` + + +## /transaction-result/{transactionResultId} + + +`TransactionResultRetrieval` + +GET endpoint used to retrieve transaction results from the payment terminal. In case you do not provide a callbackURL and token in the transaction request, the terminal will post the transaction result to an Handpoint internal API which can be queried in order for your software to fetch the transaction result. If you are running a server to receive results and pass a callback URL and token as part of the transaction request you do not need to query this endpoint. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Path parameter: transactionResultId` Required
*String* | The transactionResultId is a unique transaction id delivered immediately as a response to your transaction request. It can be used to query for a transaction result. | + + +**Returns** + + +| Response | Response Code | +| ----------- | ----------- | +| **No Content** | Response code 204. The transactionResultId was found in the database but there is no transaction result associated yet. This status will be retrieved while the transaction is ongoing and the transaction result has not been delivered yet. | +| **OK** | Response code 200 + Transaction Result. The transactionResultId was found in the database and the associated Transaction Result object is delivered. | +| **Not Found** | Response code 404. The transactionResultId was not found in the database. | + + +**Code Example** + +```shell +Operation executed using CLI tool CURL: +REQUEST: + curl -X GET \\ + -H"ApiKeyCLoud: MeRcHaNt-ApIkEy" \\ + "https://cloud.handpoint.com/transaction-result/0821032398-1628774190395" (production) + "https://cloud.handpoint.io/transaction-result/0821032398-1628774190395" (development) + +RESPONSE: +{ + "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" +} +``` + +:::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. +::: + +## /transactions/{guid}/tip-adjustment + + +`TipAdjustment` + +POST endpoint used to execute a tip adjustment operation. + +A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled by the processor at the end of the day. Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and VANTIV. + +Note: If two tip adjustments are sent for the same original transaction, only the second one will be taken into account. Each new tip adjustment will override the previous one. A tip adjustment will be rejected if the original transaction has already been batched out by the acquirer. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Path parameter: guid` Required
*String* | The guid of the transaction to be adjusted. | +| `Request Body: Tip Adjustment` Required
[TipAdjustment](restobjects.md#tip-adjustment) | Object containing the amount and currency of the tip adjustment. | + +**Returns** + + +| Response | Response Code | +| ----------- | ----------- | +| **OK** | Response code 200. | +| **BadRequest** | Response code 400. | + + +**Code Example** + +```shell +Operation executed using CLI tool CURL: +REQUEST: + curl --location --request POST 'https://cloud.handpoint.com/transactions/ff6da784-8b57-11ed-9891-ebe2a88ff071/tip-adjustment' (production)\ + curl --location --request POST 'https://cloud.handpoint.io/transactions/ff6da784-8b57-11ed-9891-ebe2a88ff071/tip-adjustment' (development)\ + --header 'ApiKeyCloud: MeRcHaNt-ApI-KeY' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "amount": 5.25 + }' + +RESPONSE code 200: +{ + "statusMessage": "tip adjusted" +} + +Error example response (using invalid guid): +{ + "error": { + "statusCode": 400, + "name": "BadRequestError", + "message": "Invalid guid [fake-guid]" + } +} +``` + +## Transaction Result Recovery + + +`TransactionResultRecovery` + + The terminal has a transaction recovery loop to automatically send back the pending TransactionResult to the callback URL in case it becomes unreachable (network issue or server down). + + For the first 100 seconds after a transaction is completed, a background thread will attempt to deliver the result every 5 seconds. If the server is still unreachable after the first 100 seconds, the retry loop turns into an exponential increment to the power of 2 (8s-16s-32s etc…). + The recovery loop is reinitialized every time the Handpoint application is restarted or the startRecovery method is triggered. The Transaction Result received through the transaction recovery loop will have the **recoveredTransaction** field set to **true**. + + All 2XXs http response codes from the callbackUrl are valid to notify the payment terminal of a successful delivery of the result. + + **Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [Transaction Result](restobjects.md#transaction-result-object) | The [Transaction Result](restobjects.md#transaction-result-object) is delivered to the callback URL from the [Transaction Request](restobjects.md#transaction-request-object). | + + + +## /transactions/{transactionReference}/status + +:::warning +This endpoint does **not** use **https://cloud.handpoint.(io/com)/** as a base URL, it uses **https://transactions.handpoint.(io/com)/** +::: + + +The `https://transactions.handpoint.com/transactions/{transactionReference}/status` endpoint is a RESTful API endpoint designed to retrieve the status of the first transaction associated with a given `transactionReference`. This endpoint returns the status of the initial transaction linked to the reference, reflecting the current state of that transaction.The `transactionReference` is a unique value that you need to generate and pass in the original [ transaction request](restobjects.md#transactionRequest). + +The main transaction result [*FinancialStatus*](restobjects.md#financialStatus) that can be returned as a response to this method are the following ones: + +- AUTHORISED - Transaction was successful. +- DECLINED - Transaction was declined. +- UNDEFINED (NOT FOUND) - 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. +- IN_PROGRESS - The transaction has been received by the gateway but the outcome is not known yet, try again after a few seconds. +- REFUNDED - Transaction was refunded. + + + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required *String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Path parameter: transactionReference` Required
*String* | The `transactionReference` is a **UNIQUE** [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) generated by you and added as a parameter to the initial financial request. It can then be used to query the transaction status endpoint. | + +:::caution +Handpoint does not verify that the `transactionReference` values sent on every request are **UNIQUE**. +It's our recommendation that a new value is created and sent for every request attempt. +::: + +**Responses** + +| Response | Response Code | +| ----------- | ----------- | +| **OK** | Response code **200** + [Transaction Result](restobjects.md#transaction-result-object).
There are two possible outcomes:
- The `transactionReference` was found in the database and the associated [Transaction Result](restobjects.md#transaction-result-object) object is delivered. By checking the [financial status](restobjects.md#financialStatus) field you will be able to know the status of the transaction at the time of the query.
- The `transactionReference` was not found in the Handpoint gateway. The [financial status](restobjects.md#financialStatus) received in this case will be `UNDEFINED` (NOT FOUND)| +| **Unauthorized** | Response code **401**. The client request has not been completed because it lacks valid authentication credentials for the requested resource. Please check your API Key is correct for this `transactionReference`. | +| **Forbidden** | Response code **403**. Authentication was unsuccessful. Please check your API Key is valid. | + +**Code Example** + +```shell +Operation executed using CLI tool CURL: +REQUEST: + curl -X GET \\ + -H"ApiKeyCLoud: MeRcHaNt-ApIkEy" \\ + "https://transactions.handpoint.com/transactions/3e665342-a95b-49c1-b6fe-b3f102305a76/status" (production) + "https://transactions.handpoint.io/transactions/3e665342-a95b-49c1-b6fe-b3f102305a76/status" (development) + +RESPONSE: +{ + "aid": "A0000000031010", + "arc": "00", + "iad": "06011103A00000", + "tsi": "0000", + "tvr": "0000000000", + "cardEntryType": "ICC", + "cardLanguagePreference": "", + "currency": "USD", + "type": "SALE", + "tipAmount": 0, + "totalAmount": 100, + "requestedAmount": 100, + "dueAmount": 0, + "tipPercentage": 0, + "efttimestamp": "20230511110113006", + "originalEFTTransactionID": "", + "paymentScenario": "CHIPCONTACTLESS", + "verificationMethod": "UNDEFINED", + "authorisationCode": "123456", + "cardSchemeName": "Visa", + "cardToken": "", + "maskedCardNumber": "************5733", + "cardTypeId": "", + "customerReference": "", + "efttransactionID": "66d94f20-efda-11ed-929c-47fffda5f9b5", + "transactionID": "66d94f20-efda-11ed-929c-47fffda5f9b5", + "errorMessage": "", + "expiryDateMMYY": "0924", + "issuerResponseCode": "00", + "rrn": "0000511573740", + "tenderType": "CREDIT", + "unMaskedPan": "", + "merchantAddress": "Navalaosa 48770 Madrid", + "merchantName": "Hago la cama 2", + "mid": "", + "cardHolderName": "", + "chipTransactionReport": "", + "customerReceipt": "", + "merchantReceipt": "", + "signatureUrl": "", + "statusMessage": "", + "tid": "", + "transactionReference": "3e665342-a95b-49c1-b6fe-b3f102305a76", + "transactionOrigin": "", + "finStatus": "AUTHORISED" +} +``` + +## /transactions/{transactionReference}/status/{selector} + +:::warning +This endpoint does **not** use **https://cloud.handpoint.(io/com)/** as a base URL, it uses **https://transactions.handpoint.(io/com)/** +::: + +The `https://transactions.handpoint.io/transactions/{transactionReference}/status/{selector}` endpoint is a RESTful API that retrieves the status of transactions associated with a given `transactionReference`. The `{selector}` path parameter allows you to specify whether you want to retrieve the status of a specific transaction by its index or retrieve all transactions associated with the `transactionReference`. + +**Selector Values** + +| Selector | Description | +| ------------- | ----------- | +| all | Returns the status of all transactions associated with the given `transactionReference`. | +| first | Returns the status of the first transaction associated with the `transactionReference`. | +| last | Returns the status of the last transaction associated with the `transactionReference`. | +| {index} | Returns the status of a specific transaction identified by its 1-based index in the sequence of transactions associated with the `transactionReference`. For example, `1` for the first transaction, `2` for the second, and so on. | + + +:::caution +**Important Note:** The `finStatus` field for the first transaction reflects its current status. In contrast, for subsequent transactions, the finStatus reflects the original status at the time of processing. For example, if a refund is later reversed, the refund transaction will still show as AUTHORISED. +::: + + +**Parameters** + +| Parameter | Description | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required *String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Path: transactionReference` Required
*String* | The `transactionReference` is a **UNIQUE** [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) generated by you and added as a parameter to the initial financial request. It is used to query the transaction status.| +| `Path: selector` Required *String* | Specifies whether to return all transactions or a specific transaction by index. | + +:::caution +Handpoint does not verify that the `transactionReference` values sent on every request are **UNIQUE**. +It's our recommendation that a new value is created and sent for every request attempt. +::: + +**Responses** + +| Response | Response Code | +| ----------- | ----------- | +| **200 OK** | The request was successful, and the transaction status(es) are returned in the response.| +| **404 Not Found** |The specified `transactionReference` or `selector` does not exist.| +| **403 Forbidden** | Authentication failed. Please check that your API Key is valid.| + + +**Example Request** + + - Retrieve All Transactions: + + ```shell + curl -X GET \ + -H "ApiKeyCloud: your-api-key" \ + "https://transactions.handpoint.io/transactions/123e4567-e89b-12d3-a456-426614174000/status/all" + ``` + + + - Retrieve third transaction + + ```shell + curl -X GET \ + -H "ApiKeyCloud: your-api-key" \ + "https://transactions.handpoint.io/transactions/123e4567-e89b-12d3-a456-426614174000/status/3" + ``` + +## Device Control Commands + +> **Note:** +> The following commands are available for all devices running Android SDK version 7.1006.0 or later. + +Command Endpoint Format + +All device control commands follow this endpoint structure: +```https://cloud.handpoint.io/devices/{deviceType}/{serialNumber}/{command}``` + +Where: +- `{deviceType}` is the type of the device (e.g., PAXIM30) +- `{serialNumber}` is the serial number of the device (e.g., 1640013848) +- `{command}` is the specific command to execute + +Common Parameters + +All commands share these common parameters: + +| Parameter | Notes | +| ----------- | ----------- | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | +| `Header: Content-Type` Required
*String* | Must be set to `application/json` | + +Common Response Codes + +| Response Code | Description | +|--------------|-------------| +| 202 | Request accepted, command will be executed | +| 403 | Authentication failed | +| 422 | Invalid request | +| 400 | Invalid parameter value (when applicable) | + +--- + +:::caution +For the Commands to work properly, the Handpoint Payments App **MUST** be in **Integrated Mode** (enabled via **Handpoint TMS** and controlled by the merchant in the **Handpoint Payments App** Settings). Use the [`pingDevice` operation](restobjects#operation-types-description) to confirm the device is in Integrated Mode before you send these commands.
+If you attempt to send one of these commands and the device is not yet in Integrated Mode, you may receive a **202 Accepted** response but the command will not have been executed by the terminal. +::: + +### Set Unattended Mode + +`POST /devices/{deviceType}/{serialNumber}/set-unattended-mode` + +Enables or disables unattended mode on the device. +Unattended mode will disable the Bottom navigation bar containing the Home, back, recent buttons. +The Payment screen will be the only visible screen in the Handpoint Payments App. (Settings, Hisotry and Analytic tabs will not be accessible) + + +**Request Body Parameters** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `status` | boolean | `true` to enable unattended mode, `false` to disable | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "status": false + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/set-unattended-mode" +``` + +### Set Locale + +`POST /devices/{deviceType}/{serialNumber}/set-locale` + +Sets the locale of the target device. + +**Request Body Parameters** + +| Parameter | Type | Description | +|-----------|--------|-----------------------------------------------------------------------------| +| `locale` | string | IETF BCP 47 language tag (e.g., `en_US`). Two-letter language and country code.| + +**Response Codes** + +| Code | Description | +|------|---------------------------------------------| +| 202 | The request is accepted and will be executed| +| 403 | Authentication failed | +| 422 | Invalid request | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "locale": "en_CA" + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/set-locale" +``` + +--- + +### Set Password Protection + +`POST /devices/{deviceType}/{serialNumber}/set-password-protected` + +Enables or disables password protection on the device. + +**Request Body Parameters** + +| Parameter | Type | Description | +|-----------|---------|-----------------------------------------------------| +| `status` | boolean | `true` to enable password protection, `false` to disable | + +**Response Codes** + +| Code | Description | +|------|---------------------------------------------| +| 202 | The request is accepted and will be executed| +| 403 | Authentication failed | +| 422 | Invalid request | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "status": true + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/set-password-protected" +``` + +--- + +### Reboot Device + +`POST /devices/{deviceType}/{serialNumber}/reboot` + +Reboots the device with an optional force parameter. + +**Request Body Parameters** + +| Parameter | Type | Description | +|-----------|---------|-----------------------------------------------------------------------------| +| `force` | boolean | `true` to force reboot even during transaction, `false` to check status first| + +**Response Codes** + +| Code | Description | +|------|---------------------------------------------| +| 202 | The request is accepted and will be executed| +| 403 | Authentication failed | +| 422 | Invalid request | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "force": false + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/reboot" +``` + +--- + +### Set Screen Brightness + +`POST /devices/{deviceType}/{serialNumber}/set-screen-brightness` + +Sets the screen brightness levels. + +**Request Body Parameters** + +| Parameter | Type | Description | +|--------------------------|---------|------------------------------------| +| `minimumBrightnessLevel` | integer | Value between 0 and 100 | +| `maximumBrightnessLevel` | integer | Value between 0 and 100 | + +**Response Codes** + +| Code | Description | +|------|---------------------------------------------| +| 202 | The request is accepted and will be executed| +| 403 | Authentication failed | +| 422 | Invalid request | +| 400 | Value is outside the valid range | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "minimumBrightnessLevel": 20, + "maximumBrightnessLevel": 100 + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/set-screen-brightness" +``` + +--- + +### Set Reboot Time + +:::note +This feature is only enabled for production devices. +::: + +`POST /devices/{deviceType}/{serialNumber}/set-reboot-time` + +Sets the daily reboot time for the device. The actual reboot will occur at a random minute within the specified hour. + +**Request Body Parameters** + +| Parameter | Type | Description | +|-----------|---------|-----------------------------------------------------| +| `hour` | integer | Hour of the day (0-23) when device should reboot | + +:::tip +If hour is set to 22, the device will reboot at a random time between 22:01 and 22:59. +::: + +**Response Codes** + +| Code | Description | +|------|---------------------------------------------| +| 202 | The request is accepted and will be executed| +| 403 | Authentication failed | +| 422 | Invalid request | +| 400 | Value is outside the valid range | + +**Example Request** + +```shell +curl -X POST \ + -H "ApiKeyCloud: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" \ + -H "Content-Type: application/json" \ + -d '{ + "hour": 22 + }' \ + "https://cloud.handpoint.io/devices/PAXIM30/0000000000/set-reboot-time" +``` \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restintroduction.md b/restapi_versioned_docs/version-REST API 2.23.1/restintroduction.md new file mode 100644 index 0000000..5252785 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restintroduction.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 1 +id: restintroduction +--- + +# Introduction +Use the Handpoint REST API to integrate leading smartpos terminals with your software. The Handpoint REST API is a simple REST interface that acts as a bridge between **your software and the payment terminal** , while shielding your software from unmasked card data. It is seamless to integrate, keeps you out of PCI scope, works with every platform, and lets you use the best Android terminals on the market. + +Complete your integration in just three steps: Initiate the interface, choose the terminal, and start the sale. It is as simple as it sounds. The only thing you need is a valid API key to authenticate against the API. Simply execute the financial operation, and within seconds you’ll get back the transaction result and receipts in your software. The Handpoint REST API seamlessly starts and manages the entire point to point encrypted transaction with the payment terminal, minimizing hassle for you and maximizing reliability, security, and control. + +## API Overview + +When integrating with the Handpoint REST API, there are 2 possible transaction flows in order to get back the transaction result from the payment terminal to your application: + +1. **Run a server to receive the transaction result**. In this scenario you will need to specify a callback URL in the transaction request. At the end of the transaction, the payment terminal will send back the transaction result to the specified callback URL. + +2. **Query an endpoint provided by Handpoint**. In this scenario a transaction result id is delivered immediately to your application as a response to the transaction request. In order to retrieve the transaction result, a specific API endpoint needs to be queried with the transaction id once the financial operation is completed on the payment terminal. + +## Transaction flow + +:::tip + +1. Pre-requisite: request your test credentials (API key) and a payment terminal from Handpoint. + +2. ensure you are targeting the correct environment. If your payment terminal is a **debug** terminal then the development environment (.io) needs to be targeted. If your payment terminal is a **demo** terminal or a **production** terminal then the production environment (.com) needs to be targeted. Demo terminals are production terminals linked to a mock acquirer so **funds are not moved**. To check if you should be using the production or the development environment you can refer to this guide: ["How do I know what type of card reader I have?"](https://hndpt.co/39utmzi) + + **For production terminals the endpoint to target is:** https://cloud.handpoint.com/ + + **For debug terminals the endpoint to target is:** https://cloud.handpoint.io/ + +::: + +The following flow shows the interactions between your application and the Handpoint REST API: + +**1)** Initialize your interface with the API key and receive the list of payment terminals available to perform a financial operation. Each API key is unique per merchant and needs to be configurable in your backend. Select a payment terminal and send a POST [transaction request](restobjects.md#transaction-request-object) to the REST API. + +**2)** The API will validate the request body and will immediately respond back to your software with the response code 202 ("Accepted”) to confirm that the data has been correctly forwarded to the payment terminal. Depending on your request body, a transactionResultId might be returned by the Handpoint API at this step (see 4.2 below). + +**3)** The validated transaction request object is forwarded to the payment terminal and the transaction starts. + +**4.1) If the original transaction request contains a callbackUrl and token** , the [transaction result](restobjects.md#transaction-result-object) will be sent back from the payment terminal to your software by using the callbackUrl. The token is a unique value generated by your software, it will be echoed in the custom HTTP header called AUTH-TOKEN of the transaction result sent by the terminal to your server. We recommend to use the token in order to authenticate the messages hitting your endpoint. The terminal expects a response back from your server when you receive the transaction result, 2XXs http response codes from the callbackUrl are considered as valid by the payment terminal to acknowledge a successful delivery of the transaction result. **See figure 4.1 below**. + +:::warning + +If you're going to use **4.1**, make sure to use an ssl certificate whose certification authority is supported by the versions of Android running on the payment terminals (Android versions vary between Android 5 and Android 10 depending on the terminal model) +::: + + **4.2) If the original transaction request does not contain a callbackUrl and token** , the [transaction result](restobjects.md#transaction-result-object) is sent back from the terminal to Handpoint's REST-API. The transaction result can then be retrieved from the endpoint GET [transaction-result/{transactionResultId}](restendpoints#transaction-resulttransactionresultid) where the transactionResultId (also called cloud transaction identifier) is found in the immediate answer from the initial transaction request POST to the REST-API (see step 2). **See figure 4.2 below**. + + + + + + + diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restobjects.md b/restapi_versioned_docs/version-REST API 2.23.1/restobjects.md new file mode 100644 index 0000000..c6942dd --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restobjects.md @@ -0,0 +1,826 @@ +--- +sidebar_position: 7 +id: restobjects +--- + +# Objects + + +## Acquirer + +`Acquirer` Enum + + +An enum representing the supported acquirers for merchant authentication. + +**Possible values** + +`AMEX` `BORGUN` `OMNIPAY` `POSTBRIDGE` `TSYS` `VANTIV` `SANDBOX` + + +## Balance + +`Balance` Object + + +Balance available on the card. + + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `amount`
*Integer* | The balance| +| `currency`
*Currency* | The balance currency| +| `positive`
*Boolean* | Defines if the balance is positive| +| `negative`
*Boolean* | Defines if the balance is negative| + +**Code example** + +````json +"balance": { + "amount": 1000, + "currency": "EUR", + "negative": false, + "positive": true + } +```` + +## Bypass Options + + +`BypassOptions` Object + + +Configuration to enable/disable signature or pin bypass. + +| Property | Description | +| ----------- | ----------- | +| `pinBypass`
*Boolean* | Enables/disables pin bypass. 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. | +| `signatureBypass`
*Boolean* | Enables/disables signature bypass. 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; 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. | + +**Code example** + +````json +{ + "bypassOptions": { + "signatureBypass": true, + "pinBypass": true + } +} +```` + +## Card Entry Type{#cardEntryType} + +`CardEntryType` Enum + +An enum representing different card entry types. + +**Possible values** + +`UNDEFINED` `MSR` `ICC` `CNP` + + +## Card Scheme Name {#cardSchemeName} + +`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` `VND` `VUV` `WST` `XAF` `XCD` `XOF` `XPF` `YER` `ZAR` `ZMK` `ZWL` `USD` `UZS` `VEF` + + +## Device {#deviceObject} + +`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* | Payment terminal shared secret key to authenticate financial operations.| +| `terminal_type` Required
*String* | Payment terminal name composed of two parts "serial_number - terminal_type".| + +**Code example** + +````json +{ + "merchant_id_alpha": "Test_Merchant", + "serial_number": "614004878", + "ssk": "74817EA5C63437ADE7AA3A5401", + "terminal_type": "PAXA920" +} +```` + +## Device Status{#deviceStatus} + +`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 milli volts of the payment terminal.| +| `BatteryCharging`
*String* | The battery charging status of the payment terminal.| +| `ExternalPower`
*String* | The status of the external power of the payment terminal.| +| `ApplicationName`
*String* | The application name used on the payment terminal.| +| `ApplicationVersion`
*String* | The application version number used on the payment terminal.| +| `bluetoothName`
*String* | The bluetooth interface name used on the payment terminal.| +| `statusMessage`
*String* | Device human readable status message.| + + +**Code example** + +````json +{ + "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} + +`Financial Status` Enum + +An enum representing different statuses of a completed transaction. + +`UNDEFINED` `AUTHORISED` `DECLINED` `REFUNDED` `PROCESSED` `FAILED` `CANCELLED` `PARTIAL_APPROVAL` `IN_PROGRESS` `REFUNDED` `CAPTURED` + +Description of the different financial statuses: + +| Parameter | Notes | +| ----------- | ----------- | +| `UNDEFINED` (NOT FOUND) *
|The `UNDEFINED` (NOT FOUND) status can be returned as a response to the [get transaction status](restendpoints.md#transactionstransactionreferencestatus) request. 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](restendpoints.md#transactionstransactionreferencestatus) request. 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](restendpoints.md#transactionstransactionreferencestatus) 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](restendpoints.md#transactionstransactionreferencestatus) method. + + +## Merchant Auth + +`MerchantAuth` Object + +An object used to store merchant authentication parameters. This object is optional, it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office. + + + +| Property | Description | +| ----------- | ----------- | +| `Credential`
[*Credential[]*](#merchant-auth-credential) | Array of credentials| + +**Code example** + +````json +{ + "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*](#acquirer) | If present, it links this credential to the specified 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** + +````json +{ + "acquirer": "ACQ_DUMMY", + "mid": "1111", + "tid": "2222", + "mcc": "3333" +} + +{ + "externalId": "4444" +} +```` + +## Metadata{#metadata} + +`Metadata` Object + +An object to store metadata. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `metadata1`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata2`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata3`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata4`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `metadata5`
*String* | An arbitrary string containing any information/data. Max length 250 characters
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| + +**Code example** + +```json +{ + "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** + +| Property | Description | +| ----------- | ----------- | +| `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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3))| + +**Code example** + +```json +{ + "moneyRemittanceOptions":{ + "fullName":"John Doe", + "countryCode":"USA" + } +} +``` + +## Operation Type + +`OperationType` Enum + + +An enum representing different types of operations. + + +Possible Values: + +`sale` `refund` `refundReversal` `saleReversal` `saleAndTokenizeCard` `tokenizeCard` `printReceipt` `cardPan` `pingDevice` `stopCurrentTransaction` `moToSale` `moToRefund` `moToReversal` `moToPreAuthorization` `preAuthorization` `preAuthorizationIncrease` `preAuthorizationCapture` `preAuthorizationReversal` + + + +## Operation Types Description + +`OperationTypesDescription` + + +| Parameter | Notes | +| ----------- | ----------- | +| `sale`
*String* | Sends a sale transaction to the payment terminal. This is the most basic operation used to withdraw funds from the cardholder's bank account. | +| `refund`
*String* | Sends a refund transaction to the payment terminal. This operation moves funds from the merchant account to the cardholder´s credit card. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night. | +| `refundReversal`
*String* | A refund reversal, also called refund VOID, allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. | +| `saleReversal`
*String* | A sale reversal, also called sale VOID allows the merchant to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. | +| `saleAndTokenizeCard`
*String* | A sale operation which also returns a card token. This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice. | +| `tokenizeCard`
*String* | Returns a card token (representing the card number). This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice. | +| `printReceipt`
*String* | Print on demand functionality allowing the merchant to print any HTML formatted receipt. It is possible to print images or barcodes as well as passing directly a URL to the printReceipt function. A bitmap can also be printed, in order to do so it needs to be rendered as an image and inserted into the html. 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. **The format of the HTML data, stored in the URL or passed in the value of the `receipt` key, must follow this format: [HTML Print Format](https://handpoint.atlassian.net/wiki/spaces/PD/pages/1409875969/Html+Print+Format)** | +| `cardPan`
*String* | A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards. | +| `pingDevice`
*String* | This operation will ping the terminal to confirm if it is ready to process transactions. `returnDeviceInfo` can be se to `true` in the body parameters to return device information like App Version, Sdk Version, Firmware Version and Battery information | +| `stopCurrentTransaction`
*String* | Operation used to stop the current transaction. The transaction can only be stopped at specific stages of payment processing, for example a transaction can not be stopped when the card is being read but can be stopped when waiting for the cardholder to initially insert a card. | +| `moToSale`
*String* | Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase. | +| `moToRefund`
*String* | A MOTO refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. Triggering this function will prompt a card input form on the terminal for the merchant to enter the card number, expiry date and CVV of the card to be charged. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund. | +| `moToReversal`
*String* | A MOTO reversal, also called VOID allows the user to reverse a previous MOTO sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund. | +| `moToPreAuthorization`
*String* | A MOTO pre-authorization, sends a pre-authorization transaction to the payment terminal. A pre-authorization charge is a temporary hold placed on a customer’s payment card. It’s used to verify that the account is valid and has sufficient funds to cover a pending transaction. | +| `preAuthorization`
*String* | A pre-auth initiates a pre-authorization operation to the card reader. In it's simplest form you only have to pass the amount and currency but it also accepts tip configuration and a map with extra parameters. A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. | +| `preAuthorizationIncrease`
*String* | This operation allows the merchant to **increase/decrease** the amount of a previously performed pre-auth operation. For example, if a tab was opened at a restaurant and the consumer is adding new orders going above the initial pre-authorized amount, it is required to increase the amount of the initial pre-authorization before capturing it. If the merchant wants to release part of a pre-auth, an increase with **negative** amount should be passed to the function.| +| `preAuthorizationCapture`
*String* | A pre-authorized transaction can be captured to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank.
**Please note that a pre-authorization can only be captured ONCE, multiple partial captures are not allowed**. If for some reason, the pre-authorization was captured for an incorrect amount, you can attempt to reverse the capture (does not work with all acquirers). If the capture reversal was declined, the cardholder needs to come back into the store with his card to get refunded or re-authorize the transaction. Alternatively, the cardholder can give his card details over the phone to the merchant and a MOTO pre-auth or MOTO refund can be issued.
Check out the [card brand rules](restobjects.md#pre-auth-capture-card-brand-rules). | +| `preAuthorizationReversal`
*String* | A **Pre-Auth/Capture Reversal** allows the user to reverse a previous pre-auth operation. This operation reverts (if possible) a specific pre-auth identified with a transaction id. A pre-authorized reversal transaction **will release the whole pre-authorized amount**, for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged. For partial releases, please check the Pre-Auth Increase/Decrease operation.
A Pre-Auth/Capture reversal can be used to reverse a capture operation as well. A capture reversal transaction **will release all the funds withheld**. Reversing a capture operation can only be done before the funds are automatically settled at night, please note that not all acquirers support reversal of captured transactions. If a capture reversal is attempted after the funds have been moved, the operation will receive a decline.
When the capture is reverted it returns to the previous state ([CAPTURED](restobjects.md#financialStatus) -> [AUTHORISED](restobjects.md#financialStatus)). | + + +### Pre-Auth Capture Card Brand Rules + +Card schemes set specific rules around which businesses are able to use pre-auth transactions. Eligibility is determined based on the Merchant Category Code (MCC), together with the card scheme. + +Card schemes have their own set of rules on authorisation expiry. Capturing a transaction after the scheme expiry time increases the risk of a failed capture, and may also increase the interchange and/or scheme fees charged for the transaction. Card schemes can also expire an authorisation before or after the official scheme expiry period has been reached. You can often capture a payment successfully after an authorisation has expired. Depending on the card scheme, there can be a fee for late capture, and an increase in interchange fee. The risk of cardholder chargebacks increase as well. + + +| Scheme | MCC | +| ----------- | ----------- | +| Mastercard | All MCCs except 5542 | +| Visa | All MCCs except 5542 | +| Discover | 3351-3441, 3501-3999, 4111, 4112, 4121, 4131, 4411, 4457, 5499, 5812, 5813, 7011, 7033, 7996, 7394, 7512, 7513, 7519, 7999 | +| American Express | All MCCs except 5542 | + +**VISA rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 3501-3999, 7011 | Lodging | 31 days | 15% | +| 3351-3500, 7512 | Car Rental | 31 days | 15% | +| 4411 | Steamship and Cruise Lines | 31 days | 15% | +| 7513 | Truck Rentals | 7 days | 15% | +| 7033 | Trailer Parks and Campgrounds | 7 days | 15% | +| 7519 | Motor Home and Recreational Vehicle Rentals | 7 days | 15% | +| 5552 | Electric Vehicle Charging | 7 days | 15% | +| 7523 | Parking and Garages | 7 days | 15% | +| 7394 | Equipment, Tool, Furniture and Appliance Rental | 7 days | none | +| 7999 | Recreation Services | 7 days | none | +| 7996 | Amusement Parks, Carnivals, Circuses, Fortune Tellers | 7 days | none | +| 5599 | Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers | 7 days | none | +| 4457 | Boat Rentals and Leasing | 7 days | none | +| 5571 | Motorcycle Shops and Dealers | 7 days | none | +| 4111 | Local and Suburban Commuter, Passenger Transportation, including Ferries | 7 days | 25 USD (or equivalent amount in local currency) | +| 4112 | Passenger Railways | 7 days | 25 USD (or equivalent amount in local currency) | +| 4131 | Bus Lines | 7 days | 25 USD (or equivalent amount in local currency) | +| 5812 | Eating Places and Restaurants | Same day | 20% | +| 5813 | Drinking Places, Bars, Taverns, Cocktail Lounges, Nightclubs, Discotheques | Same day | 20% | +| 4121 | Taxicabs and Limousines (Card-Absent Environment only) | Same day | 20% | + +**MASTERCARD rules** + +| MCC | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- | +| All MCCs | 30 days | 20% | + +**Maestro rules** + +| MCC | Segment | Authorization timeframe | Amount tolerance (captured amount above pre-authorized amount) | +| ----------- | ----------- | ----------- |----------- | +| 5812 | Eating Places and Restaurants | 7 days | 20% | +| 5814 | Fast Food Restaurants | 7 days | 20% | + +**AMEX rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| All MCCs | 7 days | +Note: Pre-Auth with AMEX is only available in the United States/Canada with the processor TSYS. + +**Discover rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | 10 days | + +**Diners rules** + +| MCC | Debit/credit | Authorization timeframe | +| ----------- | ----------- | ----------- | +| Car Rental, Hotel/Lodging MCCs | All | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Credit | 30 days | +| All MCCs except Car Rental and Hotel/Lodging | Debit | 7 days | + + +**JCB rules** + +| MCC | Authorization timeframe | +| ----------- | ----------- | +| Hotel and Car rental | Time of stay/rental | +| All MCCs except Hotel and Car rental | 1 year | + + +## Payment Scenario{#paymentScenario} + + +`PaymentScenario` Enum + + +An enum representing different types of payment scenario. + +**Possible values** + +`UNKNOWN` `MAGSTRIPE` `MAGSTRIPECONTACTLESS` `CHIP` `CHIPCONTACTLESS` `CHIPFAILMAGSTRIPE` `MOTO` + + +## 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** + +| Property | Description | +| ----------- | ----------- | +| `cancelAllowed`
*boolean* | A `boolean` Letting the integrator know if the terminal will accept a stop transaction request.) | +| `status`
[*Status*](#status) | A `Status` enum representing the status of the transaction. | +| `message`
*String* | A `String` containing the status message of the transaction. | +| `deviceStatus`
[*DeviceStatus*](#device-status) | A `DeviceStatus` object containing information about the payment terminal. | + + +## Tender Type{#tenderType} + +`TenderType` Enum + + +An enum representing different tender types. + +Possible values + +`NOT_SET` `CREDIT` `DEBIT` + + +## Tip Adjustment + +`TipAdjustment` Object + + +| Property | Description | +| ----------- | ----------- | +| `amount`
*Biginteger* | Exact amount of the tip, including decimal digits. Currency will be extracted from the original transaction. | + +**Code example** + +````json +{ + "amount": 10.25 +} + +{ + "amount": 20 +} +```` + +## Tip Configuration + +`TipConfiguration` Object + + +| Property | Description | +| ----------- | ----------- | +| `baseAmount`
*String* | 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* | List of percentages used to calculate the tip amount. | +| `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** + +````json +{ + "tipConfiguration":{ + "baseAmount":"2000", + "headerName":"", + "tipPercentages":[ + 5, + 10, + 15, + 20, + 25 + ], + "enterAmountEnabled":true, + "skipEnabled":false, + "footer":"Thank you!!! ;)" + } + } +```` + +## Transaction Request Object {#transactionRequest} + +`TransactionRequest` Object + + +An object to store information about the request sent to the payment terminal. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `operation` Required
[*OperationTypesDescription*](#operation-types-description) | The type of operation to be performed. | +| `serial_number` Required
*String* | Payment terminal serial number. | +| `terminal_type` Required
*String* | Type of terminal. | +| `callbackUrl`
*String* | If used,this is the url the payment terminal will use to send the Transaction Result once the operation is complete. All 2XXs http response codes from the callbackUrl (your server) are valid to notify the terminal of a successful delivery of the result. If the callbackUrl is not present, the device will send back the transaction result to Handpoint's REST-API and results can be retrieved using the Transaction Result Retrieval endpoint. | +| `token`
*String* | If used, the token is a unique value per operation generated by your software and used to authenticate the transaction result sent through the callbackUrl against your server. The token will be injected in the request header with key value 'AUTH-TOKEN'. **REQUIRED** when the callbackUrl is present. | +| `customerReference`
*String* | Transaction identifier provided by your software. The customerReference sent in the TransactionRequest object is echoed in the TransactionResult. In case the transaction outcome is unknown (network issue or other) and for some unknown reason your software did not receive any result. The customerReference can be used to query the Handpoint Transaction API and check if a specific transaction was approved or not: https://txnfeedapi.handpoint.com/#api-Transactions-getTxnByCustomerReference. | +| `amount`
*String* | Amount of the transaction - in the minor unit of currency (f.ex. 1000 is 10.00 GBP). **REQUIRED** for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard. | +| `currency`
[*Currency*](#currency) | The currency of the transaction. **REQUIRED** for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard. | +| `originalTransactionId`
*String* | The transaction id of the original operation to be reversed. Only required to reverse or refund a transaction and for operations linked to a pre-authorisation. **REQUIRED** for operations: refundReversal, saleReversal, LINKED refunds, preAuthorizationIncrease, preAuthorizationCapture and preAuthorizationReversal. | +| `receipt`
*String* | HTML receipt, following the format defined in Html Print Format, or url to locate the receipt, it can be found in the response of a Transaction Request, in the fields merchantReceipt or customerReceipt. **REQUIRED** for operations: printReceipt. 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. | +| `tipConfiguration`
[*TipConfiguration*](#tip-configuration) | Configuration to enable tipping. At the time of sale, a tip menu will be shown to the cardholder with the predefined configuration. The tip configuration is optional and can only be used with the sale and saleAndTokenize operations. | +| `bypassOptions`
[*ByPassOptions*](#bypass-options) | Configuration to enable the possibility of bypassing signature or pin. The bypass configuration is optional and can only be used with the sale, saleAndTokenize and refund operations. | +| `merchantAuth`
[*MerchantAuth*](#merchant-auth) |Object used to store merchant authentication. it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office. The merchantAuth is optional and can only be used with the sale, saleAndTokenize and refund operations. For reversals, the credentials passed for the original sale will be automatically looked up by Handpoint and used to process the reversal. | +| `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".| +| `metadata`
[*Metadata*](#metadata) | Object used to store metadata, this data will be echoed in the transaction result.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `transactionReference`
*String* | The `transactionReference` is a unique ([UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))) that you need to generate and add to every transaction request. In case something goes wrong and you do not receive a transaction result from the terminal, you will be able to query the Handpoint gateway directly with this id by using the [get transaction status](restendpoints.md#transactionstransactionreferencestatus) endpoint.| +| `MoneyRemittanceOptions`
[*MoneyRemittanceOptions*](restobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions. The supported operations are Sale, Sale & Tokenize, Refund, Linked Refunds, Reversals, MoTo Sale, MoTo Refund | +| `tokenize`
*Boolean* | Used to enable the tokenization flow in Tokenized Payments Operationss. See [Android SDK 7.1009.5](/android/androidreleasenotes#710095) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information.| +| `cardPresent`
*Boolean* | Optional parameter to indicate that a reversal operation will imply an actual present card, and this will be taken into account in the payments flow. See [Android SDK 7.1010.5](/android/androidreleasenotes#710105) and [Handling card present reversals with Elavon acquirers](https://handpoint.atlassian.net/wiki/spaces/PD/pages/5104533505/Handling+card+present+reversals+with+Elavon+acquirers) for detailed information on how to use this feature.| + +**Code example** + +````json +// Result will be served to result.com +{ + "operation": "sale", + "amount": "10000", + "currency": "EUR", + "terminal_type": "PAXA920", + "serial_number": "1547854757", + "customerReference": "storeSale12548", + "callbackUrl": "https://result.com", + "token": "123456789", + "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f", + "tipConfiguration": { + "baseAmount": "2000", + "tipPercentages": [5,10,15,20,25], + "enterAmountEnabled": true, + "skipEnabled": false, + "footer": "Thank you!!! ;)" + }, + "bypassOptions": { + "signatureBypass": true, + "pinBypass": true + }, + "merchantAuth": [{ + "acquirer": "ACQ_DUMMY", + "mid": "1111", + "tid": "2222", + "mcc": "3333", + "externalId": "4444" + }], + "duplicate_check": true, + "metadata": { + "metadata1": "data1", + "metadata2": "data2", + "metadata3": "data3", + "metadata4": "data4", + "metadata5": "data5" + }, + "moneyRemittanceOptions":{ + "fullName":"John Doe", + "countryCode":"USA" + } +} + +// Result will be served back to Handpoint's REST-API +{ + "operation": "sale", + "amount": "10000", + "currency": "EUR", + "terminal_type": "PAXA920", + "serial_number": "1547854757", + "customerReference": "storeSale12548", + "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f", + "tipConfiguration": { + "baseAmount": "2000", + "tipPercentages": [5,10,15,20,25], + "enterAmountEnabled": true, + "skipEnabled": false, + "footer": "Thank you!!! ;)" + }, + "bypassOptions": { + "signatureBypass": true, + "pinBypass": true + }, + "merchantAuth": [{ + "acquirer": "ACQ_DUMMY", + "mid": "1111", + "tid": "2222", + "mcc": "3333", + "externalId": "4444" + }], + "duplicate_check": true, + "metadata": { + "metadata1": "data1", + "metadata2": "data2", + "metadata3": "data3", + "metadata4": "data4", + "metadata5": "data5" + }, + "moneyRemittanceOptions":{ + "fullName":"John Doe", + "countryCode":"USA" + } +} +```` + + +## Transaction Result Object {#transactionResult} + +`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) | Balance available on the card| +| `batchNumber`
*String * | If available from the acquirer, the batch number where this transaction has been included| +| `budgetNumber`
*String * | Used to split payments over a period of months| +| `cardEntryType`
[*CardEntryType*](#cardEntryType) | Method used by the terminal to read the card| +| `cardLanguagePreference`
*String * | Preferred language of the card (EMV tag 5F2D)| +| `cardSchemeName`
[*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*](#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*](#deviceStatus) | Status of the payment terminal| +| `dueAmount`
*BigInteger * | 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`
*BigInteger * | 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*](#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*](#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*](#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*](#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*](#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*](#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 unique UUID associated with the transaction, it can be used to query the [get transaction status](restendpoints.md#transactionstransactionreferencestatus) endpoint.| + +**Code example** + +````json +{ + "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": "data1", + "metadata2": "data2", + "metadata3": "data3", + "metadata4": "data4", + "metadata5": "data5" + }, + "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": "Mr/Mrs card holder full name", + "transactionReference": "3e665342-a95b-49c1-b6fe-b3f102305a76" +} + +```` + + +## Transaction Type{#transactionType} + +`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` + + + +## Verification Method{#verificationMethod} + +`VerificationMethod` Enum + +An enum representing the possible verification methods used during the transaction. + +Possible values: + +`UNDEFINED` `SIGNATURE` `PIN` `PIN_SIGNATURE` `FAILED` `NOT_REQUIRED` `MOBILE_PASS_CODE` diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restprocessingpayments.md b/restapi_versioned_docs/version-REST API 2.23.1/restprocessingpayments.md new file mode 100644 index 0000000..91e60f2 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restprocessingpayments.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 3 +id: restprocessingpayments +--- + +# Trigger Amounts + +Your test payments are sent against a test server on the Handpoint side which simulates the behavior of an acquiring bank. Funds are not moved and sensitive data from the card is fully encrypted. You can use trigger amounts to generate some specific responses from our servers: + +**Sale amounts** + +| Amount | Behaviour | +| ----------- | ----------- | +| 37.79 | Issuer response code = 01 (Refer to issuer) | +| 37.84 | Issuer response code = 05 (Not authorized) | +| 37.93 | Issuer response code = 04 (Pick up card) | +| 37.57 | Request is partially approved | +| 37.68 | Request timeout | + +:::tip +Supporting partial approval is **mandatory** for the US market. Partial authorization occurs when a payment card authorization is attempted for a transaction and there are not enough funds available in the account to cover the full amount. The issuer returns an authorization for the amount available in the account, leaving you to obtain an additional form of payment from the customer for the balance. +::: \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.23.1/restreleasenotes.md new file mode 100644 index 0000000..5b1b534 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restreleasenotes.md @@ -0,0 +1,127 @@ +--- +sidebar_position: 2 +id: restreleasenotes +--- + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 2.23.1 +**Features:** + +The batch number is returned in the Transaction Result object now as `batchNumber`, provided the acquirer returns it. Please see [Transaction Result Object](restobjects.md#transactionResult) + +## 2.23.0 +**Bug fixes:** + +Support for MOTO operations in the Get Transaction Status service has been added + +## 2.22.4 +**Bug fixes:** + +Internal performance issues have been solved. + +## 2.22.3 +**Bug fixes:** + +A external vulnerability has been addressed. + +## 2.22.2 +**Features:** + +A new `cardPresent` parameter is available under [Optional Transaction Parameters](restobjects.md#transactionRequest). See [Android SDK 7.1010.5](/android/androidreleasenotes#710105) and [Handling card present reversals with Elavon acquirers](https://handpoint.atlassian.net/wiki/spaces/PD/pages/5104533505/Handling+card+present+reversals+with+Elavon+acquirers) for detailed information on the purpose of this feature. + +## 2.20.0 +**Features:** + +Added a selector to the [{transactionReference}/status](restendpoints.md#transactionstransactionreferencestatusselector) endpoint which improves greatly on reporting + +Added "commands" to allow greater device control options + +A new `tokenize` parameter is available under [Optional Transaction Parameters](restobjects.md#transactionRequest). See [Android SDK 7.1009.5](/android/androidreleasenotes#710095) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature. + +## 2.17.0 +**Features:** + +We're excited to announce the latest update to our REST API, featuring support of Mastercard MoneySend fields for money remittance merchants. In order to use this functionality, we provide you with an object called [Money Remittance Options](restobjects.md#money-remittance-options), which must be used in the operation. + +The supported operations are Sale, Sale & Tokenize, Refund, Linked Refunds, Reversals, MoTo Sale, MoTo Refund. For Linked Refunds and Reversals, Money Remittance fields should be taken from the original Sale/MoTo/Refund when using the field `originalTransactionID`. + +***Please note**: Money Remittance is available only for some acquirers and geographies. Please check with your Handpoint relationship manager about the availability of this functionality for your merchants. + + +## 2.15.0 +**Features:** + +We are introducing a new transaction type called [Pre-Authorization](restobjects#operation-types-description). A pre-authorization charge, also known as a pre-auth or authorization hold, is a temporary hold placed on a customer's payment card. It's used to verify that the account is valid and has sufficient funds to cover a pending transaction, without actually debiting the cardholder's account upfront. + +A pre-authorized transaction can be increased or decreased (Pre-Auth Increase), for example if a tab was opened and the consumer is adding new orders going above the initial pre-authorized amount. + +A pre-authorized transaction can be captured (Pre-Auth Capture) to actually debit the cardholder's account. Depending on the merchant category code, the capture needs to happen between 7 and 31 days after the original pre-authorization. If not captured the funds will be automatically released by the issuing bank. + +A pre-authorized transaction can be fully released (Pre-Auth Reversal), for example when renting a car, the pre-auth reversal allows the merchant to release the funds if the car was not damaged. + +In the [POSTMAN Collection](restapidownloads) section you will find sample code for each of these operations. + +## 2.14.0 +**Features:** + +We are introducing a new feature called [Get Transaction Status](restendpoints.md#transactionstransactionreferencestatus). This new [endpoint](restendpoints.md#transactionstransactionreferencestatus) allows you to query the Handpoint Gateway for the status of a transaction at any given time. You can use this feature to track the progress of your payments and troubleshoot any issues that may arise. This feature is available for all payment methods and currencies. + +When a financial operation is started from the REST API, you need to provide a `transactionReference` in the body of the transaction [request](restobjects.md#transactionRequest). This `transactionReference` can then be used to query the status of a transaction (using the [transaction status](restendpoints.md#transactionstransactionreferencestatus) endpoint) if you are not receiving the result from the terminal in a timely fashion. The `transactionReference` must be a unique identifier ([UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))). + +Example request/response to the transaction status endpoint: + + + +## 2.13.0 + +**Features:** + +We are introducing a new feature called [**Transaction Metadata**](restobjects.md#metadata). This new feature helps the customer to persist and echo back some data that belongs to the customer business domain at transaction time. The Transaction Metadata is sent in the request and echoed back in the response from the gateway. In addition, customers will be able to use the Transaction Metadata to search matching transactions from our Transaction Feed API.***** + +The Transaction Metadata feature will be available when the Handpoint Payments app **v4.1.0** or higher is used. + +***Please note**: Transactions will be available in TXN Feed API only if the request has reached the gateway. + +**Fixes:** + +- Parsing errors from the gateway (Tip Adjustment). + +## 2.12.0 +**Features:** +- New endpoint [Tip-Adjustment](restendpoints.md#transactionsguidtip-adjustment). + +A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled by the processor at the end of the day. + + +## 2.10.0 +**Features:** + +We are introducing a new feature called duplicate payment check. Looking back at our data we have seen that 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 now flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the 2nd charge. This menu will automatically be prompted on the payment terminal if a suspicious charge is detected. We are only prompting the duplicate 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 will be **enabled by default** when the Handpoint Payments app **v4.0.0.** or higher is used. V2.10.0 of the REST API only allows you to disable the duplicate payment check feature if you wish to not support it. + +The new `duplicate_check` parameter is available under the [Transaction Request Object](restobjects.md#transactionRequest). + +## 2.7.1 +**Features:** +- New endpoint to create, get and delete API keys for Merchants + +## 2.7.0 +**Features:** + +- Mail/Telephone Order functionality +- Retry logic for transaction triggering + +## 2.6.0 +**Features:** +- Endpoints for virtual terminals + +## 2.4.0 +**Features:** + +- Transaction result retrieval through API endpoint GET .../transaction-result/{transactionResultId} diff --git a/restapi_versioned_docs/version-REST API 2.23.1/restsandbox.md b/restapi_versioned_docs/version-REST API 2.23.1/restsandbox.md new file mode 100644 index 0000000..0ec32b7 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.1/restsandbox.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 5 +id: restsandbox +--- + +# Handpoint Sandbox + +Get started today with the Handpoint sandbox and test payment transactions right in your browser. The sandbox is available here: http://www.handpoint.com/lab/cloudpos. **A payment terminal is required to start testing.** + + +This is the initial setup screen: + + + +To get started, select the target environment in which you are going to operate (Sandbox or Production). If you have any doubts selecting the correct environment, click on "*How do I know what type of card reader I have?*" and you will be redirected to an explanation page. + + + +Next, enter your Handpoint API key in the box labeled "*INSERT API KEY*” and save. This action will automatically populate the “*SELECT A DEVICE*” drop down with the list of payment terminals assigned to your test account. If the API key is not valid, an error message will appear in the “RESPONSES” section of the sandbox. + + + +In the “*SELECT A DEVICE*” list choose any of the payment terminals assigned to your account. You can refresh the “*SELECT A DEVICE*” list by clicking the refresh button on the right side of the “*SELECT A DEVICE*” box. If you are already connected to a device, you can disconnect from it using the “*Disconnect*” button or trigger a software and configuration update operation by using the "*Update*" button. + + + +Once you have selected a device, the “SELECT A DEVICE” box will be disabled, and the rest of the sandbox will be enabled. With your selected device, you can simulate a number of operations, including: + +- Sale +- Sale and tokenize +- Refund +- Tokenize card +- Reverse sale transactions +- Reverse refund transactions + +In order to reverse a transaction, a transaction id is needed, this id is available in the transaction result data coming from a previous sale or refund operation. Each transaction result will appear in the RESPONSES panel, on the right side of the screen. + +With each transaction result you will be able to perform several operations: +- View and print the merchant receipt +- View and print the customer receipt +- Reverse the transaction +- Copy the transaction result data, it is the raw JSON transaction result, as received by the application from the payment terminal. + + \ No newline at end of file diff --git a/restapi_versioned_sidebars/version-REST API 2.23.1-sidebars.json b/restapi_versioned_sidebars/version-REST API 2.23.1-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/restapi_versioned_sidebars/version-REST API 2.23.1-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/restapi_versions.json b/restapi_versions.json index 61c455f..cd00d71 100644 --- a/restapi_versions.json +++ b/restapi_versions.json @@ -1,4 +1,5 @@ [ + "REST API 2.23.1", "REST API 2.23.0", "REST API 2.22.4", "REST API 2.22.3",