diff --git a/README.md b/README.md index 1c34961..30fa995 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,78 @@ This is the source code for the [Handpoint Documentation website](https://develo ## Local Development -### Requirements +### Requirements -Docusaurus is essentially a set of npm packages. If you want to build the site locally, you will need to have [Node.js](https://nodejs.org/en/) version 18 or above installed. +To build the site locally, you will need to have the following installed: +- [Node.js](https://nodejs.org/en/) version 18 or above +- [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) +- [Docusaurus](https://docusaurus.io/) -You'll also have to install [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable). +### Installing Node 18 -### Installation +If you don't have Node 18 installed, you can use **Node Version Manager**, also known as [nvm](https://github.com/nvm-sh/nvm) to install it. Nvm is a bash script that allows you to manage multiple versions of Node.js on your machine. It is a great tool for developers who need to switch between different versions of Node.js for different projects. -To install the dependencies, run: +To install nvm, you can use the following command: + +```shell +brew install nvm +``` + +Once installed, you should create NVM's working directory if it doesn't exist: + +```shell +mkdir ~/.nvm +``` + +Additionally, add the following lines to your shell profile e.g. ~/.profile or ~/.zshrc: ```bash +export NVM_DIR="$HOME/.nvm" +[ -s "/usr/local/opt/nvm/nvm.sh" ] && \. "/usr/local/opt/nvm/nvm.sh" # This loads nvm +[ -s "/usr/local/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/usr/local/opt/nvm/etc/bash_completion.d/nvm" # This loads nvm bash_completion +``` + +After installing nvm, you can install Node 18 by running the following command: + +```shell +nvm install 18 +``` + +To verify it was installed correctly, you can check the version of Node.js by running: + +```shell +node -v +``` + +Once Node 18 is installed, you can set it as the default version by running: + +```shell +nvm alias default 18 +``` + +### Installing NPM + +NPM (Node Package Manager) is included with Node.js, so you don't need to install it separately. However, if you want to update it to the latest version, you can run: + +```shell +npm update -g npm +``` + +### Installing Yarn + +Yarn is a package manager used to manage dependencies in JavaScript projects. It is an alternative to npm and is known for its speed and reliability. + +To install Yarn, you can use the following command: + +```shell +npm install --global yarn +``` + +### Install dependencies with Yarn + +To install the project dependencies, move to the root folder of the project and run: + +```shell yarn install ``` @@ -26,21 +87,88 @@ In the root folder we must execute the following commands: yarn start ``` -This command starts a local development server and opens up a browser window (by default localhost:3000). Most changes are reflected live without having to restart the server. +This command starts a local development server and opens up a browser window (by default **localhost:3000**). Most changes are reflected live without having to restart the server. + +Closing the browser window or the tab will stop the server. You can also stop the server by pressing `Ctrl + C` in the terminal. + +## How the documentation is organized + +Documentation is mainly organized in folders, classified by every SDK type available for Handpoint integrators: + +- `android`: Android SDK +- `express`: Express SDK +- `ios`: iOS SDK +- `javascript`: Javascript SDK +- `restapi`: REST API +- `windows`: Windows SDK + +Every one of the above folders is replicated in their own `versioned_docs` and `versioned_sidebars` folders. This is where the versioned documentation is stored. + +For example, the Android SDK version 6.7.0 related documentation can be found in two places: + +- `android_versioned_docs/version-Android SDK 6.7.0`: Documentation. +- `android_versioned_sidebars/version-Android SDK 6.7.0-sidebars.json`: Sidebar configuration. + +Additionally to these folders, there are other folders that are used for the website: + +- `blog`: Blog entries. +- `docs`: Documentation not directly related with SDKs (for example FAQs and introduction). +- `src`: Source code for the website (CSS, search bar, etc). +- `static`: Static files (images, etc). +- `txnfeedapi`: Transaction feed API documentation. +- `versioned_docs`: Versioned documentation of the tutorial. +- `versioned_sidebars`: Versioned sidebar configuration of the tutorial. + +## How to use Docusaurus with NPM + +Docusaurus is a static site generator that allows you to create documentation websites easily. It uses React and Markdown to create a fast and customizable documentation site. + +To use Docusaurus, just run the following command in the root folder of the project: + +```console +npm run docusaurus +``` + +### Docusaurus commands and options + +```console +Usage: [options] + +Options: + -V, --version output the version number + -h, --help display help for command + +Commands: + build [options] [siteDir] Build website. + swizzle [options] [themeName] [componentName] [siteDir] Wraps or ejects the original theme files into website folder for customization. + deploy [options] [siteDir] Deploy website to GitHub pages. + start [options] [siteDir] Start the development server. + serve [options] [siteDir] Serve website locally. + clear [siteDir] Remove build artifacts. + write-translations [options] [siteDir] Extract required translations of your site. + write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content. + docs:version Tag a new docs version + docs:version:ios Tag a new docs version (ios) + docs:version:javascript Tag a new docs version (javascript) + docs:version:restapi Tag a new docs version (restapi) + docs:version:windows Tag a new docs version (windows) + docs:version:express Tag a new docs version (express) + docs:version:android Tag a new docs version (android) +``` ## Generate a new SDK version Generate a new SDK version will autogenerate a folder with the docs that are currently in the selected folder. -Command to create a new version of Android SDK (e.g. version 6.8.0) +Command to create a new version of Android SDK (e.g. version 7.1009.5) ```console -npm run docusaurus docs:version:android "Android SDK 6.8.0" +npm run docusaurus docs:version:android "Android SDK 7.1009.5" ``` -`android` represents the folder where Android docs are. `"Android SDK 6.8.0"` is the name of the new version, it will appear as is on the documentation website -Automatically, it will create the new folder for this version (version-Android SDK 6.8.0) in `android_versioned_docs`. +`android` represents the folder where Android docs are. `"Android SDK 7.1009.5"` is the name of the new version, it will appear as is on the documentation website +Automatically, it will create the new folder for this version (version-Android SDK 7.1009.5) in `android_versioned_docs`. -**To see it published you have to stop docusaurus and start it again** +**To see it published you will have to restart docusaurus.** ## Deployment diff --git a/android/androideventlisteners.md b/android/androideventlisteners.md index dd79145..4eae6c1 100644 --- a/android/androideventlisteners.md +++ b/android/androideventlisteners.md @@ -20,9 +20,9 @@ You must provide a class implementing this interface when initializing the SDK f public final class EventHandler implements Events.SmartposRequired { @Override - public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } @Override - public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } @Override public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } @Override @@ -49,14 +49,14 @@ You must provide a class implementing this interface when initializing the SDK f ```java public final class EventHandler implements Events.MposRequired { - @Override - public void deviceDiscoveryFinished(List devices) { ... } @Override - public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + public void deviceDiscoveryFinished(List devices) { ... } + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } @Override - public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } @Override - public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } + public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } @Override public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } @Override @@ -82,14 +82,14 @@ You must provide a class implementing this interface when initializing the SDK w ```java public final class EventHandler implements Events.PosRequired { - @Override - public void deviceDiscoveryFinished(List devices) { ... } @Override - public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } + public void deviceDiscoveryFinished(List devices) { ... } + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { ... } @Override - public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } + public void currentTransactionStatus(StatusInfo statusInfo, Device device) { ... } @Override - public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } + public void signatureRequired(SignatureRequest signatureRequest, Device device) { ... } @Override public void endOfTransaction(TransactionResult transactionResult, Device device) { ... } @Override diff --git a/android/androidintegrationguide.md b/android/androidintegrationguide.md index 3735367..d9114a4 100644 --- a/android/androidintegrationguide.md +++ b/android/androidintegrationguide.md @@ -57,9 +57,9 @@ We **strongly** recommend you add the following to your `AndroidManifest.xml`: **2. SDK distribution** The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. -- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. -- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. -- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. +- If you are integrating your software with a **PAX debug terminal** you will need to get the **release candidates 7.xxxx.xx-RC** SDK. +- If you are integrating your software with a **PAX production terminal** you will need to get the **production** SDK. +- If you are integrating your software with an **HiLite terminal** you will need to get the **production** SDK. 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. @@ -136,18 +136,6 @@ android { } ``` -**Maven Settings** - -For production terminals: - -```xml - - com.handpoint.api - sdk - [7.1001.0,) - aar - -``` :::tip If using AndroidX you will need to switch the following flags to true:

android.enableJetifier=true

@@ -357,12 +345,12 @@ We **strongly** recommend you add the following to your `AndroidManifest.xml`: ```groovy android { - defaultConfig { - minSdkVersion 22 //Required to support all PAX & Telpo models - targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need //to add android:exported="true" or android:exported="false" in your activities - multiDexEnabled true - } + multiDexEnabled true + } packagingOptions { pickFirst '**/*.so' @@ -613,12 +601,12 @@ We **strongly** recommend you add the following to your `AndroidManifest.xml`: ```groovy android { - defaultConfig { - minSdkVersion 22 //Required to support all PAX & Telpo models - targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need //to add android:exported="true" or android:exported="false" in your activities - multiDexEnabled true - } + multiDexEnabled true + } packagingOptions { pickFirst '**/*.so' @@ -829,4 +817,4 @@ public class HandpointDelegate implements Events.MposRequired, Events.Connection 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. +Explore the rest of the documentation to see more transaction types supported and possibilities. \ No newline at end of file diff --git a/android/androidintroduction.md b/android/androidintroduction.md index 360e509..5e2a9ce 100644 --- a/android/androidintroduction.md +++ b/android/androidintroduction.md @@ -14,14 +14,11 @@ id: androidintroduction

Android SDK

- -
- :::info - Get our latest android SDK! Ask our support team to obtain access if you don't have already
- ::: + Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions.
@@ -47,11 +44,11 @@ We take care of PCI compliance so you can be kept out of PCI scope. The Handpoin ### SDK distribution -The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. -- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. -- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. -- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. +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** @@ -85,24 +82,6 @@ We **strongly** recommend you add the following to your `AndroidManifest.xml`: ### Gradle Settings -#### For production terminals (Maven): -```groovy - //Handpoint Production SDK (Production terminals) - implementation 'com.handpoint.api:sdk:7.x.x' -``` -In the `gradle.build` (Top-level build file) for production terminals (Maven): - - ```groovy - allprojects { //Handpoint Production SDK (Production terminals) - repositories { - google() - mavenCentral() - maven { url 'https://jitpack.io' } - } - } - ``` - -#### For debug terminals (Nexus) [Only applies to PAX/Telpo devices]: ```groovy //Handpoint Staging/Development SDK (Debug terminals) implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' @@ -110,7 +89,7 @@ In the `gradle.build` (Top-level build file) for production terminals (Maven): In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: ```groovy - allprojects { //Handpoint Staging/Development SDK (Debug terminals) + allprojects { repositories { google() mavenCentral() @@ -154,24 +133,6 @@ android { } ``` -### Maven Settings - -For production terminals: - -```xml - - com.handpoint.api - sdk - [7.1001.0,) - aar - -``` -:::tip -If using AndroidX you will need to switch the following flags to true:

-android.enableJetifier=true

-android.useAndroidX=true -::: - It is time to visit our **[Integration Guides](androidintegrationguide)** section. If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android/androidmigrationguide.md b/android/androidmigrationguide.md index 47511b2..0811895 100644 --- a/android/androidmigrationguide.md +++ b/android/androidmigrationguide.md @@ -75,8 +75,8 @@ public class HandpointDelegate implements ```java class KotlinClient: Events.Required, - Events.CurrentTransactionStatus, - Events.ConnectionStatusChanged { + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { ``` @@ -88,11 +88,11 @@ class KotlinClient: ```java public class HandpointDelegate implements - Events.SmartposRequired, - Events.CurrentTransactionStatus, - Events.ConnectionStatusChanged, - Events.EndOfTransaction, - Events.TransactionResultReady { + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { ``` @@ -129,7 +129,7 @@ public class HandpointDelegate implements ```java class KotlinClient: - Events.Required, + Events.Required, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus { ``` @@ -145,11 +145,11 @@ class KotlinClient: public class JavaClient implements Events.MposRequired, Events.ConnectionStatusChanged, - Events.CurrentTransactionStatus, - Events.SignatureRequired, - Events.EndOfTransaction, - Events.DeviceDiscoveryFinished, - Events.TransactionResultReady { + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { ``` @@ -186,7 +186,7 @@ public class HandpointDelegate implements ```java class KotlinClient: - Events.Required, + Events.Required, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus { ``` diff --git a/android/androidobjects.md b/android/androidobjects.md index a9bae86..ec9cd65 100644 --- a/android/androidobjects.md +++ b/android/androidobjects.md @@ -166,14 +166,14 @@ An enum representing all the supported acquirers for merchant authentication. ```java public enum Acquirer { AMEX, - BORGUN, - EVO, - OMNIPAY, - POSTBRIDGE, - INTERAC, - TSYS, - VANTIV, - SANDBOX + BORGUN, + EVO, + OMNIPAY, + POSTBRIDGE, + INTERAC, + TSYS, + VANTIV, + SANDBOX } ``` @@ -431,9 +431,9 @@ A class containing the credentials used to communicate with the payment terminal ```java { - String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; - HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret); - //We've even set a default shared secret! + String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret); + //We've even set a default shared secret! } ``` @@ -461,9 +461,9 @@ getAsyncInterface( Events.Required requiredListener , Context context , Handpoin //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 + String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + api = HapiFactory.getAsyncInterface(this, new HandpointCredentials(sharedSecret)); + //The api is now initialized. Yay! we've even set a default shared secret } ``` @@ -736,7 +736,7 @@ MoToOptions moToOptions = new MoToOptions(moneyRemittanceOptions); `OperationDto` Object -Object indicating which financial transaction type needs to be performed after tokenization of the card during a Tokenize and Modify operation. +Object indicating which financial transaction type needs to be performed after tokenization of the card during a Tokenize Payment Operation. **Properties** diff --git a/android/androidreleasenotes.md b/android/androidreleasenotes.md index cfc7bf3..9fda179 100644 --- a/android/androidreleasenotes.md +++ b/android/androidreleasenotes.md @@ -8,9 +8,187 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +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**: diff --git a/android/androidtransactions.md b/android/androidtransactions.md index dab62b1..7df8589 100644 --- a/android/androidtransactions.md +++ b/android/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) @@ -720,88 +721,7 @@ Invoked when the terminal finishes processing the transaction. | ----------- | ----------- | | *[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.| -## Tokenize And Modify -`tokenizedOperation` -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 operation is very useful for loyalty scenarios, a unique token for the card is delivered to your application in the middle of the transaction so you can lookup in your own loyalty engine if the cardholder qualifies for a discount. If the cardholder does qualify for a discount then the amount of the transaction can be modified (decreased) before the transaction is sent for processing. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `currency` Required
[*Currency*](androidobjects.md#13)| Currency of the charge| -| `operationDto` Required
[*OperationDto*](androidobjects.md#operation-dto)| An object containing information about the financial operation being performed after the initial tokenization, if not specified it will default to "sale"| -| `options` Required
[*SaleOptions*](androidobjects.md#4) / [*RefundOptions*](androidobjects.md#6)| An object to store all the customization options for a sale or a refund.| - -```java -//Tokenize a card and modifies the amount of a sale operation. -//Performs a tokenization of the card and sends the token back to you through the Events.CardTokenized event. -//Once you wish to continue the operation, execute the resume method of the object sent through the Events.CardTokenized event, along with the data for the financial operation you wish perform. -//The financial operation will be executed and the result will be received through the Events.Required EndOfTransaction event. - -Metadata metadata = new Metadata("Data 1", "Data 2", "Data 3", "Data 4", "Data 5"); - -SaleOptions options = new SaleOptions(); -options.setMetadata(metadata); - -api.tokenizedOperation(Currency.GBP,options); - -// To get the token and integrate the payment flow with your loyalty engine, implement the Events.CardTokenization interface. -class LoyaltyEngine : Events.CardTokenization { - - override fun cardTokenized(callback: ResumeCallback, cardTokenizationData: CardTokenizationData) { - // Call the loyalty engine and apply discounts based on cardTokenizationData - val finalAmount: BigInteger = ... // Calculate the final amount with discounts - // Call resume to continue the sale operation - val sale = OperationDto.Sale(finalAmount, Currency.EUR, getSaleOptions()) - // Resume the operation using the callback - callback.resume(sale) - } -} - -///////////////////////////////////////////////////////////////////////////////////////////////////////// - -//Tokenizes a card and executes a Refund, Sale Reversal or Refund Reversal. -//This operation executes the financial operation using the OperationDto parameter, in the example below a refund is processed. -//The result of both the tokenization and refund operations will be received through the Events.Required EndOfTransaction event. - -Metadata metadataRefund = new Metadata("This", "is", "a", "Refund", ":D"); - -RefundOptions refundOptions = new RefundOptions(); -refundOptions.setMetadata(metadataRefund); -OperationDto.Refund operation = new OperationDto.Refund(amount, currency, null, refundOptions); - -api.tokenizedOperation(Currency.GBP,operation,options); -``` - -**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'). -*** - - -[**cardTokenization**](androideventlisteners.md#card-tokenization) - -Invoked when the terminal finishes processing the transaction. - -*Note*: It will only be invoked in the case of a Sale operation. Refund and Reversal operations will be received straight throught the Events.Required EndOfTransaction event. -*** - -[**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` @@ -1123,3 +1043,986 @@ Invoked when the terminal finishes processing the transaction. | 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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 6.6.7/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 6.6.7/androidreleasenotes.md index 6170de5..985c0d4 100644 --- a/android_versioned_docs/version-Android SDK 6.6.7/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 6.6.7/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.6.7 diff --git a/android_versioned_docs/version-Android SDK 6.7.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 6.7.0/androidreleasenotes.md index 67e9cbc..2e7e3da 100644 --- a/android_versioned_docs/version-Android SDK 6.7.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 6.7.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.7.0 diff --git a/android_versioned_docs/version-Android SDK 6.7.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 6.7.2/androidreleasenotes.md index 3069ecb..49e6cb2 100644 --- a/android_versioned_docs/version-Android SDK 6.7.2/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 6.7.2/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.7.2 diff --git a/android_versioned_docs/version-Android SDK 6.7.3/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 6.7.3/androidreleasenotes.md index 815f35a..7c7d145 100644 --- a/android_versioned_docs/version-Android SDK 6.7.3/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 6.7.3/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.7.2 diff --git a/android_versioned_docs/version-Android SDK 6.7.4/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 6.7.4/androidreleasenotes.md index a9fb6a1..85d4357 100644 --- a/android_versioned_docs/version-Android SDK 6.7.4/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 6.7.4/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.7.4 diff --git a/android_versioned_docs/version-Android SDK 7.0.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.0.0/androidreleasenotes.md index 2c580dc..0fce27a 100644 --- a/android_versioned_docs/version-Android SDK 7.0.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.0.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.0.1 diff --git a/android_versioned_docs/version-Android SDK 7.0.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.0.1/androidreleasenotes.md index 2972937..89a7ed6 100644 --- a/android_versioned_docs/version-Android SDK 7.0.1/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.0.1/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.0.1 diff --git a/android_versioned_docs/version-Android SDK 7.0.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.0.2/androidreleasenotes.md index 63837ae..86b5075 100644 --- a/android_versioned_docs/version-Android SDK 7.0.2/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.0.2/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/android_versioned_docs/version-Android SDK 7.1001.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1001.0/androidreleasenotes.md index 9362078..a735002 100644 --- a/android_versioned_docs/version-Android SDK 7.1001.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1001.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/android_versioned_docs/version-Android SDK 7.1002.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1002.0/androidreleasenotes.md index 1c8b3d4..f5623a5 100644 --- a/android_versioned_docs/version-Android SDK 7.1002.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1002.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/android_versioned_docs/version-Android SDK 7.1004.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1004.0/androidreleasenotes.md index 9347a5e..6504ec9 100644 --- a/android_versioned_docs/version-Android SDK 7.1004.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1004.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1004.0 diff --git a/android_versioned_docs/version-Android SDK 7.1004.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1004.1/androidreleasenotes.md index 9e5c2bb..092cbb6 100644 --- a/android_versioned_docs/version-Android SDK 7.1004.1/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1004.1/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1004.1 diff --git a/android_versioned_docs/version-Android SDK 7.1004.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1004.2/androidreleasenotes.md index 3fba142..68afd36 100644 --- a/android_versioned_docs/version-Android SDK 7.1004.2/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1004.2/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1004.2 diff --git a/android_versioned_docs/version-Android SDK 7.1005.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1005.0/androidreleasenotes.md index cfc7bf3..6d34628 100644 --- a/android_versioned_docs/version-Android SDK 7.1005.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1005.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1005.0 diff --git a/android_versioned_docs/version-Android SDK 7.1005.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1005.1/androidreleasenotes.md index 5ff5102..5f47ae1 100644 --- a/android_versioned_docs/version-Android SDK 7.1005.1/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1005.1/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1005.1 diff --git a/android_versioned_docs/version-Android SDK 7.1005.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1005.2/androidreleasenotes.md index fa68e44..3cf6fe1 100644 --- a/android_versioned_docs/version-Android SDK 7.1005.2/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1005.2/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1005.2 diff --git a/android_versioned_docs/version-Android SDK 7.1005.3/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1005.3/androidreleasenotes.md index bd7e148..ec0b697 100644 --- a/android_versioned_docs/version-Android SDK 7.1005.3/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1005.3/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1005.3 diff --git a/android_versioned_docs/version-Android SDK 7.1005.4/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1005.4/androidreleasenotes.md index 74a2b1a..a7012a3 100644 --- a/android_versioned_docs/version-Android SDK 7.1005.4/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1005.4/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1005.4 diff --git a/android_versioned_docs/version-Android SDK 7.1006.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1006.0/androidreleasenotes.md index 50601bd..dfb1b26 100644 --- a/android_versioned_docs/version-Android SDK 7.1006.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1006.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1006.0 diff --git a/android_versioned_docs/version-Android SDK 7.1006.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1006.1/androidreleasenotes.md index 219e0bb..6711976 100644 --- a/android_versioned_docs/version-Android SDK 7.1006.1/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1006.1/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1006.1 diff --git a/android_versioned_docs/version-Android SDK 7.1006.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1006.2/androidreleasenotes.md index 84e0d9d..5984e31 100644 --- a/android_versioned_docs/version-Android SDK 7.1006.2/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1006.2/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1006.2 diff --git a/android_versioned_docs/version-Android SDK 7.1006.3/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1006.3/androidreleasenotes.md index 8d9b882..8f4ec8e 100644 --- a/android_versioned_docs/version-Android SDK 7.1006.3/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1006.3/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1006.3 diff --git a/android_versioned_docs/version-Android SDK 7.1008.0/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.0/androidreleasenotes.md index aac119d..ae09211 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.0/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.0/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.0 diff --git a/android_versioned_docs/version-Android SDK 7.1008.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.1/androidreleasenotes.md index 68cea4a..5e6e62f 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.1/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.1/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.1 diff --git a/android_versioned_docs/version-Android SDK 7.1008.1/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1008.1/androidtransactions.md index dab62b1..7aa3121 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.1/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1008.1/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1008.3/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.3/androidreleasenotes.md index 06b3eff..37bdff5 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.3/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.3/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.3 diff --git a/android_versioned_docs/version-Android SDK 7.1008.3/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1008.3/androidtransactions.md index dab62b1..7aa3121 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.3/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1008.3/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1008.4/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.4/androidreleasenotes.md index 174f082..a96a018 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.4/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.4/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.4 diff --git a/android_versioned_docs/version-Android SDK 7.1008.4/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1008.4/androidtransactions.md index dab62b1..7aa3121 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.4/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1008.4/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1008.5/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.5/androidreleasenotes.md index 415e4c0..e936371 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.5/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.5/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.5 diff --git a/android_versioned_docs/version-Android SDK 7.1008.5/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1008.5/androidtransactions.md index dab62b1..7aa3121 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.5/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1008.5/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1008.6/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1008.6/androidreleasenotes.md index c06a693..e0bef3b 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.6/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1008.6/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1008.6 diff --git a/android_versioned_docs/version-Android SDK 7.1008.6/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1008.6/androidtransactions.md index dab62b1..7aa3121 100644 --- a/android_versioned_docs/version-Android SDK 7.1008.6/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1008.6/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1009.5/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1009.5/androidintroduction.md index 0445acb..2cfb7b6 100644 --- a/android_versioned_docs/version-Android SDK 7.1009.5/androidintroduction.md +++ b/android_versioned_docs/version-Android SDK 7.1009.5/androidintroduction.md @@ -44,10 +44,12 @@ We take care of PCI compliance so you can be kept out of PCI scope. The Handpoin ### SDK distribution -The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. -- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. -- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. -- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. + +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.1009.5-RC.16-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.1009.5** + +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. diff --git a/android_versioned_docs/version-Android SDK 7.1009.5/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1009.5/androidreleasenotes.md index e1e92fd..7484d1b 100644 --- a/android_versioned_docs/version-Android SDK 7.1009.5/androidreleasenotes.md +++ b/android_versioned_docs/version-Android SDK 7.1009.5/androidreleasenotes.md @@ -8,7 +8,7 @@ id: androidreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1009.5 diff --git a/android_versioned_docs/version-Android SDK 7.1009.5/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1009.5/androidtransactions.md index 59744d3..806c3ab 100644 --- a/android_versioned_docs/version-Android SDK 7.1009.5/androidtransactions.md +++ b/android_versioned_docs/version-Android SDK 7.1009.5/androidtransactions.md @@ -645,6 +645,7 @@ The code example provided depends on RxJava, take a look a their documentation t | 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** @@ -653,7 +654,7 @@ The code example provided depends on RxJava, take a look a their documentation t Observable.fromCallable(new Callable() { @Override public FinancialStatus call() throws Exception { - return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); + return api.tipAdjustment(new BigDecimal(1000), currency.GBP, "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); } }) .subscribeOn(Schedulers.io()) diff --git a/android_versioned_docs/version-Android SDK 7.1010.1/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.1/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.1/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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.1/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.1/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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.1/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.1/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/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.1/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidintegrationguide.md new file mode 100644 index 0000000..f175114 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidintegrationguide.md @@ -0,0 +1,832 @@ +--- +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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. +- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. +- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +**Maven Settings** + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. diff --git a/android_versioned_docs/version-Android SDK 7.1010.1/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidintroduction.md new file mode 100644 index 0000000..71f733b --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidintroduction.md @@ -0,0 +1,174 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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.1-RC.0-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.1** + +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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +#### For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +#### For debug terminals (Nexus) [Only applies to PAX/Telpo devices]: +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +### Maven Settings + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+android.enableJetifier=true

+android.useAndroidX=true +::: + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.1/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.1/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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.1/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidreleasenotes.md new file mode 100644 index 0000000..c207f40 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/androidreleasenotes.md @@ -0,0 +1,444 @@ +--- +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.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.1/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.1/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.1/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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 7.1010.2/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.2/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.2/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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.2/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.2/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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.2/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.2/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/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.2/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidintegrationguide.md new file mode 100644 index 0000000..f175114 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidintegrationguide.md @@ -0,0 +1,832 @@ +--- +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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. +- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. +- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +**Maven Settings** + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. diff --git a/android_versioned_docs/version-Android SDK 7.1010.2/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidintroduction.md new file mode 100644 index 0000000..71f733b --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidintroduction.md @@ -0,0 +1,174 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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.1-RC.0-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.1** + +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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +#### For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +#### For debug terminals (Nexus) [Only applies to PAX/Telpo devices]: +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +### Maven Settings + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+android.enableJetifier=true

+android.useAndroidX=true +::: + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.2/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.2/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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.2/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidreleasenotes.md new file mode 100644 index 0000000..eb4bb8d --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/androidreleasenotes.md @@ -0,0 +1,451 @@ +--- +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.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.2/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.2/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.2/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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 7.1010.3/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.3/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.3/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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.3/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.3/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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.3/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.3/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/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.3/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidintegrationguide.md new file mode 100644 index 0000000..f175114 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidintegrationguide.md @@ -0,0 +1,832 @@ +--- +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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the SDK from **Nexus**. +- If you are integrating your software with a **PAX production terminal** you will need to get the SDK from **Maven Central**. +- If you are integrating your software with an HiLite terminal you will need to get the SDK from **Maven Central**. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +**Maven Settings** + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. diff --git a/android_versioned_docs/version-Android SDK 7.1010.3/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidintroduction.md new file mode 100644 index 0000000..71f733b --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidintroduction.md @@ -0,0 +1,174 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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.1-RC.0-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.1** + +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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +#### For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +#### For debug terminals (Nexus) [Only applies to PAX/Telpo devices]: +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +### Maven Settings + +For production terminals: + +```xml + + com.handpoint.api + sdk + [7.1001.0,) + aar + +``` +:::tip +If using AndroidX you will need to switch the following flags to true:

+android.enableJetifier=true

+android.useAndroidX=true +::: + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.3/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.3/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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.3/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidreleasenotes.md new file mode 100644 index 0000000..1076b09 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/androidreleasenotes.md @@ -0,0 +1,457 @@ +--- +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.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.3/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.3/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.3/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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 7.1010.5/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.5/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.5/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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.5/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.5/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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.5/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.5/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/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.5/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidintegrationguide.md new file mode 100644 index 0000000..7a9d6a0 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the **release candidates 7.xxxx.xx-RC** SDK. +- If you are integrating your software with a **PAX production terminal** you will need to get the **production** SDK. +- If you are integrating your software with an **HiLite terminal** you will need to get the **production** SDK. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. diff --git a/android_versioned_docs/version-Android SDK 7.1010.5/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidintroduction.md new file mode 100644 index 0000000..5e2a9ce --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androidintroduction.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.5/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.5/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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.5/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidreleasenotes.md new file mode 100644 index 0000000..8c375f5 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/androidreleasenotes.md @@ -0,0 +1,463 @@ +--- +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.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.5/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.5/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.5/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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 7.1010.6/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.6/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.6/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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.6/androideventlisteners.md b/android_versioned_docs/version-Android SDK 7.1010.6/androideventlisteners.md new file mode 100644 index 0000000..4eae6c1 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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.6/androideventsubscribers.md b/android_versioned_docs/version-Android SDK 7.1010.6/androideventsubscribers.md new file mode 100644 index 0000000..a997f42 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/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.6/androidintegrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidintegrationguide.md new file mode 100644 index 0000000..d9114a4 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the **release candidates 7.xxxx.xx-RC** SDK. +- If you are integrating your software with a **PAX production terminal** you will need to get the **production** SDK. +- If you are integrating your software with an **HiLite terminal** you will need to get the **production** SDK. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. \ No newline at end of file diff --git a/android_versioned_docs/version-Android SDK 7.1010.6/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidintroduction.md new file mode 100644 index 0000000..5e2a9ce --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androidintroduction.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.6/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.6/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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.6/androidreleasenotes.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidreleasenotes.md new file mode 100644 index 0000000..05dcb56 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/androidreleasenotes.md @@ -0,0 +1,475 @@ +--- +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.6 +**Features**: + +- `Partial Voids` (also known as Partial Reversals) are now supported for *TSYS* acquirer. Please see [Handling Partial Voids with TSYS](https://handpoint.atlassian.net/wiki/spaces/PD/pages/5210701825/Handling+Partial+Voids+with+TSYS) for further information on this. + +- 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.6/androidtransactions.md b/android_versioned_docs/version-Android SDK 7.1010.6/androidtransactions.md new file mode 100644 index 0000000..7df8589 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.6/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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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_docs/version-Android SDK 7.1010.7/androidapioverview.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidapioverview.md new file mode 100644 index 0000000..6b0f141 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 4 +id: androidapioverview +--- + +# 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/android_versioned_docs/version-Android SDK 7.1010.7/androiddevicemanagement.md b/android_versioned_docs/version-Android SDK 7.1010.7/androiddevicemanagement.md new file mode 100644 index 0000000..d825b7f --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androiddevicemanagement.md @@ -0,0 +1,417 @@ +--- +sidebar_position: 6 +id: androiddevicemanagement +--- + +# Terminal Management + +## Connect + +`connect` Method + +Connects to a payment terminal. Whenever the connection to the device is lost, the SDK will keep on trying to establish a connection until it’s re-established. No special actions are needed. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](androidobjects.md#17) | This parameter specifies which device type you want to connect to.| + +**Code example** + +```java +//Connect to a device +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +Device device = new Device("LocalDevice", "0821032398-PAXA920", "", ConnectionMethod.ANDROID_PAYMENT); +Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); +api.connect(device); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Each time the card reader state changes (ex : going from Connected to Disconnected) the ConnectionStatusChanged event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully.| + +## Disconnect + +`disconnect` Method + +Disconnect will stop the active connection (or reconnection process). Please note that the method ignores the current state of the payment terminal and just stops the connection. Calling disconnect might result in a commmunication error if triggered during a transaction. + +**Code example** + +```java +//Disconnects from the payment terminal +api.Disconnect(); +``` + +**Events invoked** + +[**connectionStatusChanged**](androideventlisteners.md#connectionStatusChanged) + +Causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + +## Get Device Manufacturer + +`getDeviceManufacturer` Method + + +**Code example** + +```java +Manufacturer manufacturer = api.getDeviceManufacturer(); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [*Manufacturer*](androidobjects.md#manufacturer)| The payment terminal manufacturer.| + + +## Get EMV Report + +`getEMVConfiguration` Method + +Fetches the logs from the device and reports them to the deviceLogsReady event. + +**Code example** + +```java +//Downloads logs from device +api.getDeviceLogs(); +``` + +**Events invoked** + +[**ReportResult**](androideventlisteners.md#reportResult) + +Invoked when the sdk has finished downloading the EMV report from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to device.| + + +## Get Paired Devices + +`getPairedDevices` Method + +Returns the 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 +// Get paired terminals +List devices = api.getPairedDevices(ConnectionMethod.XXX); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **`List`**| The list of payment terminals.| + +## Get Transactions Report{#getTransactionReport} + +`getTransactionsReport` Method + +Fetches your transactions report from a payment terminal. If you want to print the report, you can call [printReceipt](#print-receipt) with the string returned in [ReportResult](androideventlisteners.md#reportResult) event as parameter. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reportConfiguration` Required
[*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 cardBrandsList );` + +| Parameter | Notes | +| ----------- | ----------- | +| `cardBrandsList` Required
*List ``* | A list containing the supported card brands| + +

+ +`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 devices );` + +| Parameter | Notes | +| ----------- | ----------- | +| `devices` Required
List `` | A list of available devices.| + + +**Code example** + +```java +public final class EventHandler implements Events.DeviceDiscoveryFinished { + + @Override + public void deviceDiscoveryFinished(List devices) { + // Receiving a list of connectable payment terminals + foreach(Device device in devices) { ... } + +} + +// Remember to register the instance of this EventHandler: +this.api.registerEventsDelegate(eventHandlerInstance); +``` + +## End of transaction{#16} + +`Events.EndOfTransaction` Interface + +Implement this interface to receive an event when a transaction is complete. + +**Methods** + +`endOfTransaction( TransactionResult result , Device device );` + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2. SDK distribution** + +The Handpoint Android SDK is available on Maven central as well as the Handpoint internal Nexus server. Maven central contains the **production builds** while Nexus contains **development snapshots** of the SDK. +- If you are integrating your software with a **PAX debug terminal** you will need to get the **release candidates 7.xxxx.xx-RC** SDK. +- If you are integrating your software with a **PAX production terminal** you will need to get the **production** SDK. +- If you are integrating your software with an **HiLite terminal** you will need to get the **production** SDK. + + +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** + +**Gradle Settings** + +For production terminals (Maven): +```groovy + //Handpoint Production SDK (Production terminals) + implementation 'com.handpoint.api:sdk:7.x.x' +``` +In the `gradle.build` (Top-level build file) for production terminals (Maven): + + ```groovy + allprojects { //Handpoint Production SDK (Production terminals) + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } + } + ``` + +For debug terminals (Nexus): +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus): + + ```groovy + allprojects { //Handpoint Staging/Development SDK (Debug terminals) + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } +``` + +:::tip +If using AndroidX you will need to switch the following flags to true:

+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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // This triggers the asynchronous search for all the devices around that haven't been paired. + // You could, alternatively, search for the already paired devices + // List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Now: + // selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} + + +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost.If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. + + +## USB Integration (BluePad 50+) {#10} + +This tutorial is guiding you through all the required steps to create a basic payment application for Android devices integrated with an BluePad 50+ 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 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:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +**2.1 In the gradle.build (app module)** + +```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } +} +```` +```groovy +dependencies { + + //Handpoint Production SDK (Production devices) + implementation 'com.handpoint.api:sdk:7.x.x' +} +``` + + +**2.2 In the gradle.build (Top-level build file)** + +```groovy +allprojects { //Handpoint Production SDK + repositories { + google() + mavenCentral() + maven { url 'https://jitpack.io' } + } +} +``` + +:::tip +During the build process, a DEX error may appear. + +To be able to build, we recommend adding the following lines to the `gradle.properties` file: + +```groovy +org.gradle.jvmargs = -Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError +org.gradle.daemon = true +org.gradle.parallel = true +org.gradle.configureondemand = 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 android.content.Context; + +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.TransactionResult; + +import java.math.BigInteger; +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.MposRequired, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus, Events.SignatureRequired, Events.EndOfTransaction, Events.DeviceDiscoveryFinished, 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 a shared secret! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + // You have to replace this default shared secret by the one sent by our support team + // The shared secret is unique per merchant (not per terminal) + + //Now we need to find our device and connect to it + discoverDevices(); + } + + // Now we need to connect to a device to start taking payments. + // Let's search for them: + public void discoverDevices() { + + // OPTION 1 - Search for devices asynchronously + // For Bluetooth + this.api.searchDevices(ConnectionMethod.BLUETOOTH); + // Or, for USB + this.api.searchDevices(ConnectionMethod.USB); + // This triggers the asynchronous search for all the devices around that haven't been previously paired in the case of Bluetooth, + // or which are connected via cable in the case of USB. + + // OPTION 2 - Search for devices synchronously + // Alternatively, already paired devices can be searched in the case of Bluetooth: + List devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH); + // Or, already cable-connected devices can be searched in the case of USB: + List devices = this.api.getPairedDevices(ConnectionMethod.USB); + // And then: + selectDeviceAndConnect(devices); + // You'll receive the devices found through deviceDiscoveryFinished method. + // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished + } + + @Override + public void deviceDiscoveryFinished(List devices) { + selectDeviceAndConnect(devices); + } + + private void selectDeviceAndConnect(List devices) { + for (Device device : devices) { + if (device.getName() != null) { + // All the devices here are datecs devices + if (/* Fill your logic here */) { + this.api.connect(device); + // Now take a look at connectionStatusChanged method + break; + } + } + } + } + + // Potentially, if you know the MAC address of the Bluetooth device you want to connect to, you can skip the search and do it this way. This is an uncommon use case though. + // This is not possible in the case of a USB connection, because a concrete UsbDevice object which represents the physically connected USB device is needed + public void connect() { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", null, ConnectionMethod.BLUETOOTH); + //The Address always has to be written in UPPER CASE + //new Device("name", "address", null, ConnectionMethod.BLUETOOTH); + this.api.connect(device); + } + + @Override + public void connectionStatusChanged(ConnectionStatus status, Device device) { + if (status == ConnectionStatus.Connected) { + // Connected to device + } + } + + 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 + } + + @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 signatureRequired(SignatureRequest signatureRequest, Device device) { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + // At this step, you are supposed to display the merchant receipt to the cardholder on the android device + // The cardholder must have the possibility to accept or decline the transaction + // If the cardholder clicks on decline, the transaction is VOID + // If the cardholder clicks on accept he is then asked to sign electronically the receipt + this.api.signatureResult(true); + // This line means that the cardholder ALWAYS accepts to sign the receipt + // For this sample app we are not going to implement the whole signature process + } + + @Override + public void endOfTransaction(TransactionResult transactionResult, Device device) { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + + @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. + // For this sample app we are not going to implement this event. + } + + public void disconnect() { + this.api.disconnect(); + //This disconnects the connection + } +} +``` + +:::info +**Note about reconnections:** By default, the SDK will automatically reconnect to the last known device when the connection is lost. If you want to change this behaviour set the property Settings.AutomaticReconnection in HapiManager to **false**. +::: + +**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. \ No newline at end of file diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidintroduction.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidintroduction.md new file mode 100644 index 0000000..5e2a9ce --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidintroduction.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 1 +id: androidintroduction +--- + +# Introduction + + + + +
+
+
+

Android SDK

+
+
+ +
+
+ Get our latest android SDK! Ask our support team to obtain access if you don't have already.
+ In our Nexus Repository you will find both Development and Production SDK versions. +
+
+
+ +

+ +:::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 **``** -> `android:extractNativeLibs:"true"` + +```xml + + +``` + +- Inside the tag **``** -> `android:launchMode="singleTask"`: + +```xml + + ... + ... + +``` + +### Gradle Settings + +```groovy + //Handpoint Staging/Development SDK (Debug terminals) + implementation 'com.handpoint.api:sdk:7.x.x-RC.x-SNAPSHOT' +``` + In the `gradle.build` (Top-level build file) for debug terminals (Nexus) [Only applies to PAX/Telpo devices]: + + ```groovy + allprojects { + repositories { + google() + mavenCentral() + maven { + name = "Handpoint Nexus" + url = uri("urlProvided") //URL provided by Handpoint once you order a dev kit + credentials { //Credentials provided by Handpoint once you order a dev kit + username = 'usernameProvided' + password = 'passwordProvided' + } + } + } + } + ``` + +- Some considerations to keep in mind when using gradle (for both production and debug terminals) + + In the `gradle.build` (app module) add the following packaging options: + + ```groovy +android { + defaultConfig { + minSdkVersion 22 //Required to support all PAX & Telpo models + targetSdkVersion 29 //If using version targetSdkVersion 30 or higher, please note that you will need + //to add android:exported="true" or android:exported="false" in your activities + multiDexEnabled true + ndk { + abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64" + } + } + + packagingOptions { + pickFirst '**/*.so' + exclude 'META-INF/*' + exclude '**/anim/*.xml' + exclude '**/layout/*.xml' + exclude 'resources.arsc' + exclude 'AndroidManifest.xml' + exclude '**/animator/*.xml' + } + } + ``` + +It is time to visit our **[Integration Guides](androidintegrationguide)** section. + +If you have any questions, do not hesitate to **[Contact Us](mailto:support@handpoint.com)**. diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidmigrationguide.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidmigrationguide.md new file mode 100644 index 0000000..0811895 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidmigrationguide.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 3 +id: androidmigrationguide +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migration from 6.X to 7.X{#1} +The new version 7.X.X of our Android SDK introduces the following changes: +1. We removed the `Events.Required` interface and divided it into [3 different interfaces](androidmigrationguide.md#1-new-integration-interfaces) for a simpler and smoother integration. +2. All [financial operations](androidmigrationguide.md#3) will now be returning an [OperationStartResult](androidobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: + - The MAIN reason why we are now returning an object is because we want to give you access to the `transactionReference` field inside the `OperationStartResult` object. The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the `TransactionResult` object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. +3. 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 is pushed by our SDK and will automatically be displayed on top of your own UI when required. 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** in the Android sdk 7.0.0 and can be disabled by passing a false value as part of the sale options [`saleOptions.setCheckDuplicates(false);`](androidmigrationguide.md#4). +4. The `deviceCapabilities` event has been renamed to `supportedCardBrands`. +5. The [`saleAndTokenize`](androidtransactions#3) method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale`. + +## 1. New Interfaces + +For an easier integration with our SDK we removed the `Events.Required` interface and divided it into 3 different interfaces: + +- `Events.SmartposRequired` which are the mandatory events to subscribe to for a PAX integration. +- `Events.MposRequired` which are the mandatory events to subscribe to for an HiLite integration. +- `Events.PosRequired` which are the mandatory events to subscribe to if you are doing both a PAX AND HiLite integration. + +Here is the list of events being part of each interface: + +#### Interface SmartposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` + +#### Interface MposRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + +#### Interface PosRequired +- `Events.PendingResults` +- `Events.ConnectionStatusChanged` +- `Events.CurrentTransactionStatus` +- `Events.EndOfTransaction` +- `Events.DeviceDiscoveryFinished` +- `Events.SignatureRequired` + + + + +The changes required for each of the above scenarios is described below. + + +### Android Native Integration (PAX) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class HandpointDelegate implements + Events.SmartposRequired, + Events.CurrentTransactionStatus, + Events.ConnectionStatusChanged, + Events.EndOfTransaction, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.SmartposRequired { +``` + + + + +### Bluetooth Integration (HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.MposRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.MposRequired { +``` + + + + +### Bluetooth and Android Native Integration (PAX & HiLite) + +#### Older Implementation (Android SDK 6.X) + + + +```java +public class HandpointDelegate implements + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: + Events.Required, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus { +``` + + + + +#### Current Implementation (Android SDK 7.X) + + + +```java +public class JavaClient implements + Events.PosRequired, + Events.ConnectionStatusChanged, + Events.CurrentTransactionStatus, + Events.SignatureRequired, + Events.EndOfTransaction, + Events.DeviceDiscoveryFinished, + Events.TransactionResultReady { +``` + + + + + +```java +class KotlinClient: Events.PosRequired { +``` + + + + + +## 2. All financial operations are now returning an [OperationStartResult](androidobjects.md#operation-start-result) object instead of a boolean{#3} + +The methods affected by this change are the following: + +- [Sale](androidtransactions.md#2) +- [SaleReversal](androidtransactions.md#4) +- [Refund](androidtransactions.md#5) +- [RefundReversal](androidtransactions.md#6) +- [MotoSale](androidtransactions.md#7) +- [MotoRefund](androidtransactions.md#8) +- [MotoReversal](androidtransactions.md#9) +- [TokenizeCard](androidtransactions.md#12) +- [CardPan](androidtransactions.md#13) + + +## 3. Disabling the duplicate payment check service{#4} + +**This functionality is only available for SmartPos devices (PAX).** + +By default, the duplicate payment check service is enabled. If you want to manually disable this service you will need to set the `checkDuplicate` field to `false` using the `SaleOptions` parameter. Here is an example: + +```java +public void pay(BigInteger amount, Currency currency) { + SaleOptions saleOptions = new SaleOptions(); + saleOptions.setCheckDuplicates(false); + this.api.sale(amount, currency, saleOptions); +} +``` +You can disable the duplicate check functionality for the following financial operations: +- [Sale](androidtransactions.md#2) +- [Sale and Tokenize](androidtransactions.md#3) +- [Refund](androidtransactions.md#5) + +## 4. The `deviceCapabilities` event has been renamed to `supportedCardBrands` + + Check out the [card brand display](androideventlisteners.md#cardBrandDisplay) object. + + +## 5. The `saleAndTokenize` method has been removed. Since Android SDK 7.0.0, a `saleAndTokenizeOptions` object needs to be passed in 'options' parameter of financial operations methods like `sale` + +Check out the [Sale and Tokenize Card](androidtransactions.md#3) section. + diff --git a/android_versioned_docs/version-Android SDK 7.1010.7/androidobjects.md b/android_versioned_docs/version-Android SDK 7.1010.7/androidobjects.md new file mode 100644 index 0000000..ec9cd65 --- /dev/null +++ b/android_versioned_docs/version-Android SDK 7.1010.7/androidobjects.md @@ -0,0 +1,1216 @@ +--- +sidebar_position: 9 +id: androidobjects +--- + + + + + +# Objects + +## Transaction Result{#25} + +`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** + +| Parameter | Description | +| ----------- | ----------- | +| `aid`
*String* | Application Identifier of the card (EMV tag 9F06).| +| `arc`
*String* | EMV Authorisation Response Code (EMV tag 8A).| +| `authorisationCode`
*String* | Acquirer response code.| +| `balance`
[*Balance*](#balance) | 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 credentials ); +``` +| Parameter | Description | +| ----------- | ----------- | +| `credential`
*List* | If present, the list of credentials.| + +```java +Add Credential +add( Credential credential ); +``` + +| Parameter | Description | +| ----------- | ----------- | +| `credential` Required
[*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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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 ** + +[![Standalone Tokenized SALE Sequence Diagram](/img/standalone_tokenized_SALE.png)](/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 ** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/standalone_Tokenized_Refund_and_reversals.png)](/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** + +[![Cloud Tokenized SALE](/img/cloud_tokenized_Sale.png)](/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** + +[![Standalone Tokenized Refund, Reversal and RefundReversal Sequence Diagram](/img/cloud_tokenized_SaleReversal.png)](/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** + +[![Cloud Tokenized Refund Sequence Diagram](/img/cloud_tokenized_Refund.png)](/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** + +[![Cloud Tokenized Refund Reversal Sequence Diagram](/img/cloud_tokenized_refund_Reversal.png)](/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.1-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.1-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.1-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/android_versioned_sidebars/version-Android SDK 7.1010.2-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.2-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.2-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/android_versioned_sidebars/version-Android SDK 7.1010.3-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.3-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/android_versioned_sidebars/version-Android SDK 7.1010.5-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.5-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.5-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/android_versioned_sidebars/version-Android SDK 7.1010.6-sidebars.json b/android_versioned_sidebars/version-Android SDK 7.1010.6-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/android_versioned_sidebars/version-Android SDK 7.1010.6-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} 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 044037b..3761e1e 100644 --- a/android_versions.json +++ b/android_versions.json @@ -1,4 +1,10 @@ [ + "Android SDK 7.1010.7", + "Android SDK 7.1010.6", + "Android SDK 7.1010.5", + "Android SDK 7.1010.3", + "Android SDK 7.1010.2", + "Android SDK 7.1010.1", "Android SDK 7.1009.5", "Android SDK 7.1008.6", "Android SDK 7.1008.5", diff --git a/docusaurus.config.js b/docusaurus.config.js index e788345..ed2db3e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -175,21 +175,60 @@ module.exports = { }, }, }, - themes:[ - ['@easyops-cn/docusaurus-search-local', - {indexBlog:false, - indexPages:false, - indexDocs:true, - docsDir:['android','ios','windows','javascript','restapi','express'], - docsRouteBasePath:['android','ios','windows','javascript','restapi','express']}]], + themes: [ + ['@easyops-cn/docusaurus-search-local', { + id: 'search-android', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'android', + docsRouteBasePath: 'android', + }], + ['@easyops-cn/docusaurus-search-local', { + id: 'search-ios', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'ios', + docsRouteBasePath: 'ios', + }], + ['@easyops-cn/docusaurus-search-local', { + id: 'search-windows', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'windows', + docsRouteBasePath: 'windows', + }], + ['@easyops-cn/docusaurus-search-local', { + id: 'search-javascript', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'javascript', + docsRouteBasePath: 'javascript', + }], + ['@easyops-cn/docusaurus-search-local', { + id: 'search-restapi', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'restapi', + docsRouteBasePath: 'restapi', + }], + ['@easyops-cn/docusaurus-search-local', { + id: 'search-express', + indexBlog: false, + indexPages: false, + indexDocs: true, + docsDir: 'express', + docsRouteBasePath: 'express', + }], +], presets: [ [ '@docusaurus/preset-classic', { - googleAnalytics: { - trackingID: 'UA-1295190-6', - anonymizeIP: false, - }, docs: { sidebarPath: require.resolve('./sidebars.js'), includeCurrentVersion: true, @@ -210,9 +249,6 @@ module.exports = { ], ], scripts: [ - // String format. - 'https:////js-eu1.hs-scripts.com/25846579.js', - ], plugins: [ // require.resolve('docusaurus-lunr-search', { @@ -300,4 +336,4 @@ module.exports = { ], ] -}; +}; \ No newline at end of file diff --git a/ios/iosdevicemanagement.md b/ios/iosdevicemanagement.md index 98f35b7..2b3b8eb 100644 --- a/ios/iosdevicemanagement.md +++ b/ios/iosdevicemanagement.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 id: iosdevicemanagement --- diff --git a/ios/iosevents.md b/ios/iosevents.md index 3cadb49..a50716c 100644 --- a/ios/iosevents.md +++ b/ios/iosevents.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 id: iosevents --- diff --git a/ios/iosinstallation.md b/ios/iosinstallation.md index 4310562..9c7560b 100644 --- a/ios/iosinstallation.md +++ b/ios/iosinstallation.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 id: iosinstallation --- diff --git a/ios/iosintegration.md b/ios/iosintegration.md index 47b46cc..b42abaf 100644 --- a/ios/iosintegration.md +++ b/ios/iosintegration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 id: iosintegration --- diff --git a/ios/iosmigration.md b/ios/iosmigration.md index e4f5879..d99260b 100644 --- a/ios/iosmigration.md +++ b/ios/iosmigration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 id: iosmigration --- diff --git a/ios/iosobjects.md b/ios/iosobjects.md index 1233393..ce8d0a0 100644 --- a/ios/iosobjects.md +++ b/ios/iosobjects.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 id: iosobjects --- diff --git a/ios/iosprocessing.md b/ios/iosprocessing.md index 6d32c3e..ea2885b 100644 --- a/ios/iosprocessing.md +++ b/ios/iosprocessing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 id: iosprocessing --- diff --git a/ios/iosreleasenotes.md b/ios/iosreleasenotes.md new file mode 100644 index 0000000..8a07f74 --- /dev/null +++ b/ios/iosreleasenotes.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +id: iosreleasenotes +--- + + + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 4.0.2 +**Fixes**: +- Crash due to vector index out of bounds. + +## 4.0.1 +**Fixes**: + - Multi MID fix for INTERAC and POSTBRIDGE acquirers. + +## 4.0.0 +**Features**: + - Support for Multi MID and HiPro scanner fixes. + diff --git a/ios/iossdkprocessing.md b/ios/iossdkprocessing.md index f754bb5..b614ac1 100644 --- a/ios/iossdkprocessing.md +++ b/ios/iossdkprocessing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 id: iossdkprocessing --- diff --git a/ios/iostransactions.md b/ios/iostransactions.md index 80d2df2..a0fd2bb 100644 --- a/ios/iostransactions.md +++ b/ios/iostransactions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 id: iostransactions --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iosdevicemanagement.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iosdevicemanagement.md index dfc5cc4..ee280f9 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.0/iosdevicemanagement.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iosdevicemanagement.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 id: iosdevicemanagement --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iosevents.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iosevents.md index a9150bb..227794a 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.0/iosevents.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iosevents.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 id: iosevents --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iosobjects.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iosobjects.md index 5aceabd..6fa2116 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.0/iosobjects.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iosobjects.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 id: iosobjects --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iosreleasenotes.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iosreleasenotes.md new file mode 100644 index 0000000..78617da --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iosreleasenotes.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 2 +id: iosreleasenotes +--- + + + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 4.0.0 +**Features**: + - Support for Multi MID and HiPro scanner fixes. + diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iossdkprocessing.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iossdkprocessing.md index 2a581c3..b3ebfc1 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.0/iossdkprocessing.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iossdkprocessing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 id: iossdkprocessing --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.0/iostransactions.md b/ios_versioned_docs/version-iOS SDK 4.0.0/iostransactions.md index c24f048..400bfe4 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.0/iostransactions.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.0/iostransactions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 id: iostransactions --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/ios b/ios_versioned_docs/version-iOS SDK 4.0.1/ios deleted file mode 100644 index 376d7be..0000000 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/ios +++ /dev/null @@ -1,2599 +0,0 @@ - - -# iOS SDK 4.0.1 - - -## Introduction - - - - -The Handpoint iOS SDK provides a simple application programming interface for the Handpoint card readers. - -:::tip - -Please note that before submitting an app to the Apple App store a MFi hardware request has to be submitted to Apple, -to be able to use an external accessory. Please fill our this form before submitting your app to the App store and we will get back to you. -If you have any questions, contact us for more details. - -::: - -## Installation - - -### CocoaPods - -CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command: - -```` -$ gem install cocoapods -```` - -If you don't have a Podfile yet: - -```` -$ pod init -```` - -To integrate HandpointSDK into your Xcode project using CocoaPods, specify it in your `Podfile`: - -```` -source 'https://github.com/CocoaPods/Specs.git' -platform :ios, '8.0' -use_frameworks! - -target 'your_target' do - pod 'HandpointSDK', '~> 3.2.3' -end -```` - -Then, run the following command: - -```` -$ pod install -```` - -### Carthage - -[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. - -You can install Carthage with [Homebrew](https://brew.sh/) using the following command: - -``` -$ brew update -$ brew install carthage -``` - -To integrate HandpointSDK into your Xcode project using Carthage, specify it in your `Cartfile`: - -```` -github "handpoint/HandpointSDK-iOS" -````` - -Run `carthage update` to build the framework and drag the built `HandpointSDK.framework` into your Xcode project. - -### Manually - -If you'd rather handle the dependency manually there are three approaches to include ```HandpointSDK``` in your project: - -#### Prebuilt static library - -Download the latest pre-built static library from [Handpoint's developer portal](https://www.handpoint.com/docs/device/iOS/) and refer to the documentation there for the installation steps. - -#### Building the project yourself - -Download the latest version from the master branch: - -``` -$ git clone https://github.com/handpoint/HandpointSDK-iOS.git -``` - -Alternatively you can add it as a git [submodule](https://git-scm.com/docs/git-submodule): - -``` -$ git submodule add https://github.com/handpoint/HandpointSDK-iOS.git -``` - -### Framework - -You'll find the dynamic framework project called `HandpointSDK.xcodeproj` at the root of the repo. - -Static Library -You'll find the static library project called `headstart.xcodeproj` under the `Library` folder. - -We **strongly** discourage you from building this project yourself. - -This project contains several targets, you need to build the aggregated target `device-simulator Release` - -This target produces a .zip file in the same directory as the `headstart.xcodeproj` file containing both the library and the simulator library. - -## Migration from 3.X - - -:::tip -Version 4.0.0 introduces a well defined, typed, way of passing extra values, options, parameters or flags to the financial transactions. -::: - - -We have unified all the extra and optional parameters in an Options object. Different operations have different options. - -**1. For a [Sale](#2) or [Sale and Tokenize operation](#4) please see SaleOptions**
If you use a customer reference: - -``` - SaleOptions *options = [SaleOptions new]; - options.customerReference = @"Your customer reference"; -``` - - -If you need Multi MID / Custom merchant Authentication: - - -````objectivec - MerchantAuth *auth = [MerchantAuth new]; - Credential *cred = [Credential new]; - //Optionally - cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; - //Optionally - cred.mid = @"mid"; - //Optionally - cred.tid = @"tid"; - //Add as many credentials as Acquirers your merchant have agreements with - [auth add:cred]; - options.merchantAuth = auth; -``` - -If you want to specify the budget period `Only available for SureSwipe`: - -````objectivec -options.divideByMonths = @"YOUR_BUDGET_NUMBER"; - ```` - -Finally: - -````objectivec -[self.api saleWithAmount:amount currency:currency options:options]; -```` - - -**2. Similar to SaleOptions, but with less possible parameters, for a [Refund](#5) operation, please see RefundOptions**
If you use a customer reference: - -````objectivec - SaleOptions *options = [SaleOptions new]; - options.customerReference = @"Your customer reference"; -```` - -If you need Multi MID / Custom merchant Authentication: - -````objectivec -MerchantAuth *auth = [MerchantAuth new]; - Credential *cred = [Credential new]; - //Optionally - cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; - //Optionally - cred.mid = @"mid"; - //Optionally - cred.tid = @"tid"; - //Add as many credentials as Acquirers your merchant have agreements with - [auth add:cred]; - options.merchantAuth = auth; -```` -Finally: - -```objectivec -[self.api refundWithAmount:amount currency:currency transaction:originalTransactionID options:options]; -``` - -**3. For the rest of operations, please see Options**
If you use a customer reference: - -```objectivec -options.customerReference = @"Your customer reference"; -``` - -## Integration Guide - -### Files in iOS SDK - -#### If you're using the library/Cocoapods: - -- **HandpointAll.h**: #import this header file into your classes. -- **libheft.a**: The SDK library. - -#### If you're using the framework/Carthage: - -- ** HandpointSDK.h**: #import this header file into your classes. -- **HandpointSDK.framework**: The SDK library. - -The SDK also includes a simulator, a library configured to simulate a card reader - intended for early development of an user interface. To use it, just link the libheft.a file in the HeftSimulatorLibrary folder, instead of the actual SDK library. - -### Development settings for the SDK - -- **Dependencies**:The Heft library depends on the``` ExternalAccessory``` and ``` libc++.dylib``` frameworks included with the iOS SDK. These frameworks and the **libheft.a** SDK library itself need to be linked to your project for the Handpoint interface to work properly. - -- **Communication protocol**: Your application needs to support the card reader communication protocol. For this reason, the ```com.datecs.pinpad``` string needs to be added to the ```Supported external accessory protocols``` in the **.plist file**: - -````xml - UISupportedExternalAccessoryProtocols - - com.datecs.pinpad - -```` - -- **Background mode support**: Your application needs to support connection to external devices when in the background. For this reason, in the "Capabilities" section of the project settings, the **Background Modes** profile needs to be ON, and the ```External accessory communication ``` option must be checked. This is equivalent to adding the following entry in the .plist file: - - -````xml - UIBackgroundModes - - external-accessory - -```` - -- **C++ linker flag**: A part of the library is written in c++ therefore the **-lc++ linker flag** needs to be set. Add it under "Other Linker Flags" under the "Linking" section of your projects settings "Build Settings" tab. -- **Other settings**: To prevent the warning: "file was built for archive which is not the architecture being linked (armv7s)", **set Build Active Architecture Only** to YES. - - -### Usage summary - -Any application using the Handpoint SDK should follow these steps: - -1. Define a class that implements the** HeftDiscoveryDelegate **protocol. -This class defines the behavior of the app when discovery related events are received from the SDK. -2. Define a class that implements the **HeftStatusReportDelegate** protocol (it can be the same as above). -This class defines the behavior of the app when connection and transaction related events are received from the SDK -3. Get a reference to the HeftManager singleton and assign your HeftDiscoveryDelegate instance as delegate. -4. If device is available through BT connection, start the discovery process by calling the** startDiscovery** function of the HeftManager and recover a list of the discovered devices by calling the **connectedCardReaders **function of the HeftManager. -5. If device is using a Lightning connector (HiPro devices), recover the device by directly calling the **connectedCardReaders** function of the HeftManager. -6. Connect to a device by calling the **clientForDevice** function of the HeftManager. -7. If connection is successful, the **didConnect** function of the HeftStatusReportDelegate instance will be invoked. -8. From this point, make transactions and have fun! - -### Usage details - -1. Define a class that implements the ** HeftDiscoveryDelegate **protocol. -This class will define the behavior of the application when discovery related events are received from the SDK. - -````objectivec - @interface MyDiscoveryDelegate () - @implementation MyDiscoveryDelegate -```` - -2. Define a class that implements the** HeftStatusReportDelegate **protocol (it can be the same as above). -This class will define the behavior of the application when connection and transaction related events are received from the SDK. - -````objectivec - @interface MyStatusReportDelegate () - @implementation MyStatusReportDelegate -```` - -3. Get a reference to the HeftManager singleton in SDK by calling the **sharedManager** class method. -Assign your HeftDiscoveryDelegate instance as delegate of the manager. - -````objectivec - MyDiscoveryDelegate* myDiscoveryDelegate = [[alloc MyDiscoveryDelegate] init]; - HeftManager* manager = [HeftManager sharedManager]; - manager.delegate = myDiscoveryDelegate; -```` - -4. If device is available through BT connection, start the discovery process by calling the **startDiscovery** function of the HeftManager. - -````objectivec - [manager startDiscovery]; -```` - -When a device is selected by the user in the “Select device” popup window, the **didFindAccessoryDevice** function of the HeftDiscoveryDelegate is invoked. - -````objectivec - - (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice - { - NSLog(@"Found new device"); - //Connect to found device or store it for later - } -```` - -When the discovery process is finished, the **didDiscoverFinished** function of the HeftDiscoveryDelegate instance will be invoked. Recover a list of all the discovered devices by calling the **connectedCardReaders** function of the HeftManager. - -````objectivec - - (void)didDiscoverFinished - { - NSMutableDictionary *discoveredDevices = [self.manager connectedCardReaders]; - } -```` - -5. If device is using a Lightning connection (HiPro devices), skip the previous step and recover the device by directly calling the **connectedCardReaders** function of the HeftManager. - -````objectivec -HeftRemoteDevice *lightningDevice = [[self.manager connectedCardReaders] firstObject]; -```` - -6. Connect to a device by calling the **clientForDevice** function of the HeftManager. - -Expected parameters of this function are: - - -* A discovered device (HeftRemoteDevice object). - -* A shared secret. The shared secret is a unique identifier. It is a used to link a merchant with his readers. Each one of your merchants will be assigned a different shared secret so it needs to be a configurable value in your application or backend. If you received a development kit with a card reader, our support team probably sent you a shared secret via email already. - -* A HeftStatusReportDelegate instance, which will be notified of all the events related with the device. - -```` objectivec - // Declare the shared secret (below SS is an example, please put the one sent by our support team) - NSString *sharedSecret =@"0102030405060708091011121314151617181920212223242526272829303132"; - // Connect to reader - [manager clientForDevice:device - sharedSecret:mySharedSecret - delegate:myStatusReportDelegate]; -```` - -7. If connection is successful, the **didConnect** function of the HeftStatusReportDelegate instance will be invoked. Function receives as parameter a HeftClient object, whose reference must be stored since it is the communication bridge to the device we have connected to. - -```` objectivec - - (void)didConnect:(id )client - { - self.heftClient = client; - } -```` - -8. Once connected to the card reader, transactions can be started through the HeftClient object. For example, the next code starts a sale of 100 GBP: - -````objectivec -[self.heftClient saleWithAmount:100 currency:@"GBP" cardholder:YES]; -```` - -9. When a transaction has been initiated (f.ex saleWithAmount), the HeftClient alerts the HeftStatusReportDelegate object by invoking **responseStatus** during the process and **responceFinanceStatus** when the process has finished. - -````objectivec - - (void)responseStatus:(id)info - { - NSLog(@"responseStatus:"); - NSLog(info.status); - NSLog(info.xml.description); - } - - - (void)responseFinanceStatus:(id)info - { - NSLog(@"responseFinanceStatus:"); - NSLog(info.status); - NSLog(info.customerReceipt); - NSLog(info.xml.description); - } -```` - -10. In case you are using the **SDK simulator**, the behavior changes according to the amount of the transaction: - -| **Amount** | **Behavior** | -| ----------- | ----------- | -| 1000 | Declined transaction| -| 2000 | User Cancelled| -| 3000 | Signature Requested| -| Other amount | Approved transaction| - -## Processing Payments Simulation - -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 server: - -**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 | - -## SDK integration example - -### HandpointModule header - -**HandpointModule.h** - -````objectivec -#import "HandpointAll.h" - -@interface HandpointModule : NSObject - -- (instancetype)initWithSharedSecret:(NSString *)sharedSecret; - -- (void)saleWithAmount:(NSInteger)amount - currency:(NSString *)currency; - -- (void)refundWithAmount:(NSInteger)amount - currency:(NSString *)currency; - -- (void)saleReversalWithAmount:(NSInteger)amount - currency:(NSString *)currency - originalTransactionID:(NSString *)originalTransactionID; - -- (void)refundReversalWithAmount:(NSInteger)amount - currency:(NSString *)currency - originalTransactionID:(NSString *)originalTransactionID; - -- (void)connectToAddress:(NSString *)address; - -- (void)setLogLevel:(eLogLevel)logLevel; - -- (void)getDeviceLogs; - -- (void)getPendingTransaction; - -- (void)update; - -- (void)listDevices; - -@end -```` - -### HandpointModule - -**HandpointModule.m** - -````objectivec -#import "" -#import "HandpointModule.h" -#import "HeftRemoteDevice+SendableDevice.h" -#import "SDKEvent.h" -#import "ConnectionStatus.h" -#import "Currency.h" -#import "CDVInvokedUrlCommand+Arguments.h" -#import "StatusInfo.h" -#import "TransactionResult.h" - -typedef NS_ENUM(NSInteger, ConnectionStatus) -{ - ConnectionStatusNotConfigured, - ConnectionStatusConnected, - ConnectionStatusConnecting, - ConnectionStatusDisconnected, - ConnectionStatusDisconnecting, - ConnectionStatusInitializing -}; - -@interface HandpointModule () - -@property (nonatomic) HeftManager* manager; -@property (nonatomic, strong) id api; -@property (nonatomic) NSString *ssk; -@property (nonatomic) HeftRemoteDevice* preferredDevice; -@property (nonatomic) NSString *eventHandlerCallbackId; -@property (nonatomic) NSMutableDictionary *devices; - -@end - -@implementation HandpointModule - -- (instancetype)initWithSharedSecret:(NSString *)sharedSecret -{ - NSLog(@"\n\tpluginInitialize"); - self.manager = [HeftManager sharedManager]; - self.manager.delegate = self; - self.devices = [@{} mutableCopy]; - - [self fillDevicesFromConnectedCardReaders]; - - self.ssk = sharedSecret; -} - -- (void)saleWithAmount:(NSInteger)amount - currency:(NSString *)currency -{ - BOOL result = [self.api saleWithAmount:amount - currency:currency - cardholder:YES]; - - if (result == false) - { - //Do something - } -} - -- (void)refundWithAmount:(NSInteger)amount - currency:(NSString *)currency -{ - BOOL result = [self.api refundWithAmount:amount - currency:currency - cardholder:YES] - - if (result == false) - { - //Do something - } -} - -- (void)saleReversalWithAmount:(NSInteger)amount - currency:(NSString *)currency - originalTransactionID:(NSString *)originalTransactionID -{ - BOOL result = [self.api saleVoidWithAmount:amount - currency:currency - cardholder:YES - transaction:originalTransactionID]; - - if (result == false) - { - //Do something - } -} - -- (void)refundReversalWithAmount:(NSInteger)amount - currency:(NSString *)currency - originalTransactionID:(NSString *)originalTransactionID -{ - BOOL result = [self.api refundVoidWithAmount:amount - currency:currency - cardholder:YES - transaction:originalTransactionID]; - - if (result == false) - { - //Do something - } -} - -#pragma mark - Device Management - -- (void)connectToAddress:(NSString *)address -{ - HeftRemoteDevice *remoteDevice = self.devices[address]; - - if (remoteDevice) - { - BOOL isRemoteDeviceSameAsPreferred = self.preferredDevice && - [self.preferredDevice.address isEqualToString:remoteDevice.address]; - - // If we are already connected to this device, update shared secret - if (self.api && isRemoteDeviceSameAsPreferred) - { - // Already connected to device - } - else - { - self.preferredDevice = remoteDevice; - - [self.manager clientForDevice:remoteDevice - sharedSecret:self.ssk - delegate:self]; - } - - [self connectionStatusChanged:ConnectionStatusConnecting]; - } - else - { - NSLog(@"Can't connect. No device available. Have you searched?"); - } -} - -- (void)setLogLevel:(eLogLevel)logLevel -{ - [self.api logSetLevel:logLevel]; -} - -- (void)getDeviceLogs -{ - [self.api logGetInfo]; -} - -- (void)getPendingTransaction -{ - BOOL success = NO; - - if ([self.api isTransactionResultPending]) - { - success = [self.api retrievePendingTransaction]; - } - - if (success) - { - //... - } - else - { - //... - } -} - -- (void)update -{ - [self.api financeInit]; -} - -- (void)listDevices -{ - NSArray* devices = [self.manager connectedCardReaders]; - - /** - * A device can have four levels of connection: unpaired, paired, - * connected and connected in the SDK. - * - * Due to the nature of the iOS ExternalAccessory framework, - * devices that are already connected at an iOS level will not appear in a normal search, - * as they already appear through the "connectedCardReaders" array in the manager - * (Yeah, I know) - * - * So the "if" takes care of differentiating those two cases - * - * If we have device(s) connected we just go for those, otherwise, search. - */ - - if(devices.count) - { - //We have device(s) already connected, we skip the search. - for (HeftRemoteDevice *device in devices) - { - [self addDevice:device]; - } - - [self didDiscoverFinished]; - } - else - { - //We search and wait... - [self.manager startDiscovery]; - } -} - -# pragma mark - Callbacks - -- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice -{ - [self addDevice:newDevice]; -} - -- (void)didLostAccessoryDevice:(HeftRemoteDevice *)oldDevice -{ - [self removeDevice:oldDevice]; - - if(self.preferredDevice && self.preferredDevice.address == oldDevice.address) - { - [self connectionStatusChanged:ConnectionStatusDisconnected]; - - self.preferredDevice = nil; - } -} - -- (void)didDiscoverFinished -{ - [self fillDevicesFromConnectedCardReaders]; - - for (NSString *key in [self.devices allKeys]) - { - HeftRemoteDevice *device = self.devices[key]; - - if ([device.address isEqualToString:]) - { - //Do something with the device if it's the same one you expect. - break; - } - } -} - -- (void)didConnect:(id )client -{ - if(client) - { - self.api = client; - - [self connectionStatusChanged:ConnectionStatusConnected]; - } -} - -- (void)connectionStatusChanged:(ConnectionStatus)status -{ - //Here you get notified of connection status changes -} - -- (NSString *)stringFromConnectionStatus:(ConnectionStatus)status -{ - switch(status) - { - case ConnectionStatusNotConfigured: - return @"NotConfigured"; - case ConnectionStatusConnected: - return @"Connected"; - case ConnectionStatusConnecting: - return @"Connecting"; - case ConnectionStatusDisconnected: - return @"Disconnected"; - case ConnectionStatusDisconnecting: - return @"Diconnecting"; - case ConnectionStatusInitializing: - return @"Initializing"; - } -} - -- (void)responseStatus:(id )info -{ - //Here you'll get status updates during the transaction -} - -- (void)responseError:(id )info -{ - //Here if something went wrong -} - -- (void)responseFinanceStatus:(id )info -{ - //Here's the result of your transaction -} - -- (void)responseLogInfo:(id )info -{ - NSLog(@"\n\tresponseLogInfo: %@", info.status); -} - -- (void)requestSignature:(NSString *)receipt -{ - [self.api acceptSignature:YES]; -} - -- (void)addDevice:(HeftRemoteDevice *)device -{ - self.devices[device.address] = device; -} - -- (void)removeDevice:(HeftRemoteDevice *)device -{ - if (self.devices[device.address]) - { - [self.devices removeObjectForKey:device.address]; - } -} - -- (void)fillDevicesFromConnectedCardReaders -{ - for (HeftRemoteDevice *device in [self.manager connectedCardReaders]) - { - [self addDevice:device]; - } -} - -@end -```` - -## Transactions - -### Sale{#2} - -`saleWithAmount` - -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 *`
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `currency *`
*NSString* | 3 letter currency code in accordance to ISO4217| -| `options`
*SaleOptions* | An object to store all the customization options for a sale.| - -**Code example** - -````objectivec -//If you just need a plain vanilla sale: -[api saleWithAmount:100 - currency:Currency.EUR.alpha]; - -//But you can customize your sale: -SaleOptions *options = [SaleOptions new]; -//Optionally -options.customerReference = @"Your customer reference"; -//If you need Multi MID / Custom merchant Authentication: -MerchantAuth *auth = [MerchantAuth new]; -Credential *cred = [Credential new]; -//Optionally -cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; -//Optionally -cred.mid = @"mid"; -//Optionally -cred.tid = @"tid"; -//Add as many credentials as Acquirers your merchant have agreements with -[auth add:cred]; -options.merchantAuth = auth; -//If you want to specify the budget period -//Only available for SureSwipe -//Here it's 3 months -options.divideByMonths = @"3"; - -[api saleWithAmount:100 - currency:Currency.EUR.alpha - options:options]; -```` - -**Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader. - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**requestSignature**](#17) -*** -Invoked if card verification requires signature. - -[**responseFinanceStatus **](#16) -*** -Invoked when the card reader finishes processing the transaction - -** Returns** - -**Boolean** - -YES if operation starts successfully - -### Sale Reversal{#3} - -`saleVoidWithAmount` - -Request a void operation on previous sale transaction, referred to by the parameter transaction. Parameters amount, currency and present must be the same as the in the sale to be voided. This operation reverts (if possible) a specific sale identified with a transaction id. Note that transactions can only be reversed within the same day as the transaction was made. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `amount *`
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `currency *`
*NSString* | 3 letter currency code in accordance to ISO4217 | -| `transaction *`
*NSString* | TransactionID of the sale transaction to be voided | -| `options`
*Options* | An object to store all the customization options for this operation.| - -**Code example** - -```objectivec -//If you just need a plain vanilla sale reversal: -[api saleReversalWithAmount:100 - currency:Currency.EUR.alpha - transactionId:originalTransactionID - options:options]; - -//But you can customize your sale: -Options *options = [Options new]; -//Optionally -options.customerReference = @"Your customer reference"; - -[api saleReversalWithAmount:100 - currency:Currency.EUR.alpha - transactionId:@"00000000-0000-0000-0000-000000000000" - options:options]; -``` - -**Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError **](#15) -*** -Invoked to inform when an error response happens. - -[**responseFinanceStatus**](#16) -*** -Invoked when the card reader finishes processing the transaction - -**Returns** - -**Boolean** -YES if operation starts successfully - - -### Sale And Tokenize Card{#4} - -`saleAndTokenizeCardWithAmount` - -A sale initiates a payment operation to the card reader. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `amount *`
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `currency *`
*NSString* | 3 letter currency code in accordance to ISO4217| -| `options`
*SaleOptions* | An object to store all the customization options for a sale.| - -**Code example** - -````objectivec -//If you just need a plain vanilla sale tokenization: -[api saleAndTokenizeWithAmount:100 - currency:Currency.EUR.alpha]; - -//But you can customize your sale: -SaleOptions *options = [SaleOptions new]; -//Optionally -options.customerReference = @"Your customer reference"; -//If you need Multi MID / Custom merchant Authentication: -MerchantAuth *auth = [MerchantAuth new]; -Credential *cred = [Credential new]; -//Optionally -cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; -//Optionally -cred.mid = @"mid"; -//Optionally -cred.tid = @"tid"; -//Add as many credentials as Acquirers your merchant have agreements with -[auth add:cred]; -options.merchantAuth = auth; -//If you want to specify the budget period -//Only available for SureSwipe -//Here it's 3 months -options.divideByMonths = @"3"; - -[api saleAndTokenizeWithAmount:100 - currency:Currency.EUR.alpha - options:options]; -```` - -**Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**requestSignature**](#17) -*** -Invoked if card verification requires signature. - -[**responseFinanceStatus**](#16) -*** -Invoked when the card reader finishes processing the transaction - -**Returns** - -**Boolean** - -YES if operation starts successfully - -### Refund{#5} - -`refundWithAmount` - -A refund initiates a refund operation to the card reader. This operation moves funds from your account to the cardholders credit card. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `amount *`
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `currency *`
*NSString* | Currency of the charge| -| `transaction *`
*NSString* | If present it links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.| -| `options`
*MerchantAuthOptions* | An object to store all the customization options for a refund.| - -**Code example** - -````objectivec -//If you just need a plain vanilla refund: -[api refundWithAmount:100 - currency:Currency.EUR.alpha - transaction:@"00000000-0000-0000-0000-000000000000"]; - -//But you can customize your sale: -MerchantAuthOptions *options = [MerchantAuthOptions new]; -//Optionally -options.customerReference = @"Your customer reference"; -//If you need Multi MID / Custom merchant Authentication: -MerchantAuth *auth = [MerchantAuth new]; -Credential *cred = [Credential new]; -//Optionally -cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; -//Optionally -cred.mid = @"mid"; -//Optionally -cred.tid = @"tid"; -//Add as many credentials as Acquirers your merchant have agreements with -[auth add:cred]; -options.merchantAuth = auth; - -[api refundWithAmount:100 - currency:Currency.EUR.alpha - transaction:@"00000000-0000-0000-0000-000000000000" - options:options]; -```` - -** Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError**](#15) -*** -Invoked when the card reader finishes processing the transaction - -[**responseFinanceStatus**](#16) -*** -Invoked to inform when an error response happens. - -**Returns** - -**Boolean** - -YES if operation starts successfully - -### Refund reversal{#6} - -`refundVoidWithAmount` - -Request a void operation on previous refund transaction, referred to by the parameter transaction. Parameters amount, currency and present must be the same as the in the refund to be voided. This operation reverts (if possible) a specific refund identified with a transaction id. Note that transactions can only be reversed within the same day as the transaction was made. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `amount *`
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `currency *`
*NSString* | 3 letter currency code in accordance to ISO4217| -| `transaction *`
*NSString* | TransactionID of the refund transaction to be voided| -| `options`
*Options* | An object to store all the customization options for this operation.| - -**Code example** - -````objectivec -//If you just need a plain vanilla refund reversal: -[api refundReversalWithAmount:100 - currency:Currency.EUR.alpha - transactionId:originalTransactionID - options:options]; - -//But you can customize your sale: -Options *options = [Options new]; -//Optionally -options.customerReference = @"Your customer reference"; - -[api refundReversalWithAmount:100 - currency:Currency.EUR.alpha - transactionId:@"00000000-0000-0000-0000-000000000000" - options:options]; -```` - -** Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**responseFinanceStatus**](#16) -*** -Invoked when the card reader finishes processing the transaction - -**Returns** - -**Boolean** - -YES if the operation was successfully sent to device - -### Accept signature{#7} - -`acceptSignature` - -A [*requestSignature*](#17) event is invoked during transaction when signature verification is needed (f.ex when payment is done with a magstripe card). The merchant is required to ask the cardholder for signature and approve (or disapprove) the signature. signatureRequired tells the card reader if the signature was approved by passing YES. To disapprove then NO is passed. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `flag *`
*Boolean* | YES if signature is valid, NO otherwise| - - -**Code example** - -````objectivec -//acceptSignature: -//Inform the card reader if signature is valid or not --(IBAction)accept -{ - [heftClient acceptSignature:YES]; -} --(IBAction)decline -{ - [heftClient acceptSignature:NO]; -} -```` - -** Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**responseFinanceStatus**](#16) -*** -Invoked when the card reader finishes processing the transaction - - -### Retrieve Pending Transaction{#8} - -`retrievePendingTransaction` - -Retrieving a pending transaction fetches a transaction result that was lost due to unexpected disconnect between card reader and application. - -**Code example** - -````objectivec -//retrievePendingTransaction: -//Called when a pending transaction is discovered upon connecting to a specific card reader -- (void)didConnect:(id)client{ - heftClient = client; - - if(heftClient){ - if([heftClient isTransactionResultPending] == YES) { - // a pending transaction has been detected ... - // ... so, lets get it - [heftClient retrievePendingTransaction]; - } - } -} -```` - -** Events invoked** - -[**responseStatus**](#14) -*** -Invoked during the operation with different statuses from the card reader. - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**responseRecoveredTransactionStatus**](#18) -*** -Invoked when the card reader has returned a recovered transaction. - -**Returns** - -**Boolean** - -YES if operation starts successfully - -### Tip Adjustment{#9} - -`tipAdjustment` - -A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled automatically 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. -The tip adjustment method does not rely on a card reader and is therefore a separate method that must be initialized with a shared secret. The function is defined in the file HapiRemoteService.h - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `tipAmount *`
*NSInteger* | Tip amount added to the original (base) transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| -| `transaction*`
*NSString* | TransactionID (GUID) of the original sale transaction to be adjusted| - - -**Code example** - -````objectivec -//First, you need to include the following dependency -#include "HapiRemoteService.h" - -//Second, the shared secret needs to be initialized -NSString* shared_secret = @"0102030405060708091011121314151617181920212223242526272829303132"; -BOOL result = setupHandpointApiConnection(shared_secret); - -//Third, you need to retrieve the unique transaction id of the original sale transaction you want to adjust. The below GUID is only an example and will result in a decline from the host if used for tip adjustment -NSString* transaction = @"d50af540-a1b0-11e6-85e6-07b2a5f091ec"; - -//Fourth, let's tip adjust a transaction for $10.00! --(IBAction)tipAdjustment:(UIButton*) sender -{ - BOOL result = tipAdjustment(transaction, 1000, ^(TipAdjustmentStatus status) - { - if(status == TipAdjustmentAuthorised) { - - //Successfully adjusted! - - } - - else if(status == TipAdjustmentDeclined) { - - //Declined! - - } - - else if(status == TipAdjustmentFailed) { - - //Timeout! - - } - }); -} -```` - -**Returns** - -**status** - -- **TipAdjustmentAuthorised** (tip adjustment approved by the processor) -- **TipAdjustmentFailed** (system error or timeout) -- **TipAdjustmentDeclined** (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{#10} - -`tokenizeCard` - -Initiates a card-tokenization operation to the card reader (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice). - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `reference *`
*NSString* | string for customer reference| - - -**Code example** - -````objectivec -//Initiates a card tokenization operation. -[heftClient tokenizeCard]; -```` - - -** Events invoked** - -[**responseStatus**](#14) -*** -Invoked while during transaction with different statuses from card reader - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**requestSignature**](#17) -*** -Invoked if card verification requires signature. - -[**responseRecoveredTransactionStatus**](#18) -*** -Invoked when the card reader finishes processing the transaction - - -**Returns** - -**Boolean** - -YES if operation starts successfully - -## Device management - -### Shared Manager{#11} - -`sharedManager` - -Provides access to the heftManager. The heft manager is used for discovering devices and creating a HeftClient with a connection to selected device. - -**Code example** - -````objectivec -//SharedManager -//Provides access to the heftManager - -//Create an instance of the shared manager at set it's delegate -HeftManager* heftManager = [HeftManager sharedManager]; -heftManager.delegate = self; -```` - -**Returns** - -[**HeftManager**](#19) - -The heftManager instance - -### Client for device (NSString){#12} - -`clientForDevice` - -Creates a HeftClient object. If a connection is successful the HeftClient object is returned in the didConnect event. All transactions are done using the heftClient. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `device *`
*NSInteger* | The device to connect to.| -| `sharedSecret *`
*NSString* | Shared secret only known by the merchant and Handpoint.| -| `aDelegate *`
*BOOL* | The HeftStatusReportDelegate for the HeftClient to report to.| - - -**Code example** - -````objectivec -//clientForDevice:sharedSecretString:delegate: -//Creates a HeftClient object(connection to device) -NSString* sharedSecret = @"0102030405060708091011121314151617181920212223242526272829303132"; --(void)connectToFirstCardReaderWith:(NSString*)sharedSecret; -{ - //Try to connect to first device in devices array - [heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecretString:sharedSecret delegate:self]; - //Client calls the didConnect delegate function if successful -} -```` - -**Events invoked** - -[**didConnect**](#20) -*** -Called when a connection to specified device was created. - -**Returns** - -**Boolean** - -YES if operation starts successfully - -### Start Discovery {#32} - -`startDiscovery` - -Displays a list of available accessory devices in a modal window. - -**Code example** - -````objectivec -//startDiscovery -//Starts the BT discovery process --(void)startDiscovery; -{ - [heftManager startDiscovery]; - //Start search activity indicator or other desired functions -} -```` - -### Set log level{#33} - -`logSetLevel` - -Sets the log level of the card reader. There are for levels of logging for the device: none, info, full, debug. Setting the log level means that relevant information concerning the application operation will be stored. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `level *`
[eLogLevel](#13) | eLogLevel available types: eLogNone, eLogInfo, eLogFull, eLogDebug| - -**Code example** - -````objectivec -//logSetLevel: -//Sets the log level of the card reader. --(void)disableCardReaderLogs -{ - [heftClient logSetLevel:eLogNone]; -} --(void)enableCardReaderDebugLogs -{ - [heftClient logSetLevel:eLogDebug]; -} -```` - -**Returns** - -**Boolean** - -This method always returns YES - - -### Fetch logs{#34} - -`logSetLevel` - -Retrieves the logging info. Returns them in the responseLogInfo event. - -**Code example** - -````objectivec -//logGetInfo -//Retrieves the logging info. --(void)getLogsFromCardReader -{ - [heftClient logGetInfo]; -} -```` - -**Returns** - -**Boolean** - -This method always returns YES - -### Reset logs{#35} - -`logReset` - -Clears the logging information stored so far. - -**Code example** - -````objectivec -//logReset -//Clears the logging information stored so far --(void)clearLogs -{ - [heftClient logReset]; -} -```` - -**Returns** - -**Boolean** - -This method always returns YES - -### Enable scanner{#36} - -`enableScanner` - -Places the card reader in a scan mode. Only if the card reader supports it. To cancel/stop scan mode call the cancel method of the heft client. - -**Parameters** - - -| Parameter | Notes | -| ----------- | ----------- | -| `multiScan`
*Boolean* | Yes [default] to activate multiScan mode - No to activate singleScan mode. Multi-scan mode allows the user to scan until scan operation is canceled or timeout occurs, single-scan mode is active until one scan has occurred then it disables the scan mode.| -| `buttonMode`
*Boolean* | Yes [default] if buttonMode is on - No otherwise. If button mode is on then the operator needs to press the scan buttons to activate the scanner(during scan mode).| -| `timeoutSeconds`
*NSInteger* | 0 [default] - card reader will determine when scanning should time out. x - the scanner will time out if x seconds of inactivity occur.| - -**Code example** - -````objectivec -//enableScanner:multiScan:buttonMode:timeoutSeconds -//Places the card reader in a scan only mode. -//To cancel/stop scan mode call cancel function. --(IBAction)startScan -{ - [heftClient enableScanner]; -} --(IBAction)startMultiScan -{ - [heftClient enableScannerWithMultiScan:YES]; -} -```` - -**Events invoked** - -**responseScannerEvent** -*** -Called to inform that a scan has been performed, several calls can be expected. Several calls to this method happen after a scan action has been performed to inform about scan information operation. The info object contains scanCode, status and a dictionary (xml). - -### Disable scanner - -`disableScanner` - -Disables the scanner if possible - -**Code example** - -````objectivec -//disableScanner -//Disable the scanner - -(IBAction)disableScanner -{ -[heftClient disableScanner]; -} -```` - -**Events invoked** -*** -[**responseScannerDisabled**](#42) - -Called to inform that a scan has been performed, several calls can be expected. Several calls to this method happen after a scan action has been performed to inform about scan information operation. The info object contains scanCode, status and a dictionary (xml). - -### financeInit{#47} - -`financeInit` - -The update operation checks for update to the card reader and initiates an update if needed. The update can either be a software update or a configuration update. - -**Code example** - -````objectivec -//financeInit -//Initializes the card reader and updates config. --(IBAction)updateCardReader -{ - [heftClient financeInit]; -} -```` - -**Events invoked** - -[**responseStatus**](#14) -*** -Called to inform that a scan has been performed, several calls can be expected. Several calls to this method happen after a scan action has been performed to inform about scan information operation. The info object contains scanCode, status and a dictionary (xml).**responseStatus**](#14) - -[**responseError**](#15) -*** -Invoked to inform when an error response happens. - -[**responseFinanceStatus**](#16) -*** -Invoked when the card reader finishes processing the transaction - -**Returns** - -**Boolean** - -This method always returns YES - -### Get SDK version - -`getSDKVersion` - -Returns the current SDK version number in string format - -**Code example** - -````objectivec -//getSDKVersion -//Log SDK version number - NSLOG(@"SDK version: %@", [heftManager getSDKVersion]; -```` - -### Get SDK build number - -`getSDKBuildNumber` - -Returns the current SDK build number in string format - -**Code example** - -````objectivec -//getSDKBuildNumber -//Log SDK build number - NSLOG(@"SDK build: %@", [heftManager getSDKBuildNumber]; -```` - -## Events - -### didConnect{#20} - -`didConnect` - -Called when a connection to the client has been established through the method clientForDevice. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `client *`
[HeftClient](#22) | Yes [default] to activate multiScan mode - No to activate singleScan mode. Multi-scan mode allows the user to scan until scan operation is canceled or timeout occurs, single-scan mode is active until one scan has occurred then it disables the scan mode.| - -**Code example** - -````objectivec -//didConnect: -//Called when a connection to specified device was created. --(void)didConnect:(id)client -{ - // connected successfully to a device - // assign the client to our heftClient property - heftClient = client; -} -```` - -### didDiscoverFinished {#37} - -`didDiscoverFinished` - -When the modal window from startDiscovery is closed then this event is called. - -**Code example** - -````objectivec -//didDiscoverFinished -// This function gets called when discovery is finished -- (void)didDiscoverFinished; -{ - NSLog(@"Discover finished"); - //Stop search activity indicator or other desired functions -} -```` - - -### didFindAccessoryDevice{#38} - -`didFindAccessoryDevice` - -Notifies that new accessory device was found. When a card reader is detected this delegate is called. You can take the newDevice object and create a new heft client for that particular device or store it in memory to connect to it later. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `newDevice *`
[HeftRemoteDevice](#23) | An object containing a reference to the accessory device| - -**Code example** - -````objectivec -//didFindAccessoryDevice -//Delegate that notifies that new accessory device was found. -- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice -{ - NSLog(@"Found new device"); - //Connect to device or store found device for later -} -```` - - -### didLostAccessoryDevice{#39} - - -`didLostAccessoryDevice` - -Notifies that accessory device was disconnected. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `oldDevice *`
[HeftRemoteDevice](#23) | An object containing a reference to the accessory device| - -**Code example** - -````objectivec -//didLostAccessoryDevice -//Delegate that notifies that accessory device was disconnected -- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice -{ - NSLog(@"Device disconnected"); - //Remove device from devices array - [heftManager.devicesCopy removeObject:oldDevice]; - //Do some cleanup after disconnecting if necessary - -} -```` - -### responseStatus{#14} - -`responseStatus` - -Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about status of operation. The info object contains a string (status) and a dictionary (xml). - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[ResponseInfo](#24) | Includes status code, status text and detailed xml.| - -**Code example** - -````objectivec -//responseStatus: -//Called to inform about the status of the transaction --(void)esponseStatus:(id)info -{ - NSLog(info.status); - NSLog(info.xml.description); -} -```` - -### responseFinanceStatus{#16} - -`responseFinanceStatus` - -Notifies that transaction has completed. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[FinanceResponseInfo](#25) | Information about current transaction status.| - -**Code example** - -````objectivec -//responseFinanceStatus: -//Called at the end of transaction to inform about the result of the operation --(void)responseFinanceStatus:(id)info -{ - NSLog(info.status); - NSLog(info.customerReceipt); - //print receipts -} -```` - -### responseError{#15} - -`responseError` - -Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about status of operation. The info object contains a string (status) and a dictionary (xml). - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[ResponseInfo](#24) | The info object contains a string (status) and a dictionary (xml).| - -**Code example** - -````objectivec -//responseError: -//Called when to inform when an error response happens. --(void)responseError:(id)info -{ - NSLog(info.status); - NSLog(info.xml.description); -} -```` - -### requestSignature{#17} - -`requestSignature` - -Is called if during a financial operation a signature from the customer is needed. The requestSignature delegate should be implemented to print out or display the receipt for the customer to sign and provide the merchant with the means to confirm the signature. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `receipt *`
*NSString* | The receipt is a html formatted string containing a receipt for the customer to sign| - -**Code example** - -````objectivec -//requestSignature: -//Is called if a signature from the customer is needed. --(void)requestSignature:(NSString*)receipt -{ - NSLog(receipt); - //Display buttons to accept or decline customer signature - UIAlertView* alert = [[UIAlertView alloc] initWithTitle:@"" message:@"sign?" delegate:self cancelButtonTitle:@"No" otherButtonTitles:@"Yes", nil]; - [alert show]; -} -```` - -### cancelSignature{#40} - -`cancelSignature` - -Called if the signature request times out. If the card reader does not receive an approval for the signature within a certain timeframe (45 sec) it cancels the transaction and sends a notification to the app. - -**Code example** - -````objectivec -//cancelSignature -//Called if the signature request times out. --(void)cancelSignature -{ - NSLog(@"Signature request timed out"); -} -```` - -### responseScannerEvent{#41} - -`responseScannerEvent` - -Called to inform that a scan has been performed, several calls can be expected. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[ScannerEventResponseInfo](#26) | The info object contains scanCode, status and a dictionary (xml).| - -**Code example** - -````objectivec -//responseScannerEvent: -//Called to inform that a scan has been performed --(void)responseScannerEvent:(id)info -{ - NSLog(info.scanCode); //barcode scanned - NSLog(info.xml.description); -} -```` - -### responseScannerDisabled{#42} - -`responseScannerDisabled` - -Called to notify that the scanner has been disabled. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[ScannerDisabledResponseInfo](#27) | The info object contains information about the scanner operation.| - -**Code example** - -````objectivec -//responseScannerDisabled: -//Called to notify that the scanner has been disabled. --(void)responseScannerDisabled:(id)info -{ - NSLog(info.status); -} -```` - -### responseLogInfo{#43} - -`responseLogInfo` - -Called when logs have been downloaded from the card reader by using the logGetInfo method. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[LogInfo](#27) | The info object has the string property log which holds the log info in text with carriage returns.| - -**Code example** - -````objectivec -//responseLogInfo: -//Called when logs have been downloaded from the card reader by using the logGetInfo method. --(void)responseLogInfo:(id)info -{ - NSLog(info.log); - //write to log file -} -```` - -### responseRecoveredTransactionStatus{#44} - -`responseRecoveredTransactionStatus` - -This method is **OPTIONAL** and only required if retrievePendingTransaction will be called. - -**Parameters** - -| Parameter | Notes | -| ----------- | ----------- | -| `info *`
[*ResponseInfo*](#24) | Information about the recovered transaction status.| -| |**If an attempt was made to recover a transaction when none was pending then this parameter WILL be nil.**| - -**Code example** - -````objectivec -//responseRecoveredTransactionStatus: -//Called when a pending transaction result has been recovered from the card reader -- (void)responseRecoveredTransactionStatus:(id)info{ - if(info != nil) { - if(info.statusCode == EFT_PP_STATUS_SUCCESS) { - NSLog(info.status); - NSLog(info.customerReceipt); - NSLog(info.merchantReceipt); - // print receipts and/or save receipts in transaction log - - if(info.financialResult == EFT_FINANC_STATUS_TRANS_APPROVED){ - // Process recovered authorized transaction result - } else if(info.financialResult == EFT_FINANC_STATUS_TRANS_DECLINED) { - // Process recovered declined transaction result - } - } else if(info.statusCode != EFT_PP_STATUS_NO_DATA_AVAILABLE) { - // some other error was detected while waiting for a pending transaction result - } - } - // else a pending transaction result was not found on the card reader -} -```` - -### Card Reader Requirements - -**Version Requirements** - -Card reader software v1.7.0+ and v2.1.7+ is required in order for this response to be received. - -## Objects - -### HeftManager{#19} - -`HeftManager` - -The HeftManager is used for discovering devices and to connect and create a HeftClient object for the appropriate device. The manager reports messages to HeftDiscoveryDelegate protocol during the discovery process. Starting the manager is usually the first thing that should be done after loading up an UIView that enables the user to search for and connect to BT devices. When starting the manager an object (usually the UIViewController itself) is passed as the HeftDiscoveryDelegate delegate to report to. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `devicesCopy`
[NSArray] | **DEPRECATED_ATTRIBUTE**: Stored array which contains all found devices.| -| `connectedCardReaders`
[NSArray] | Stored array which contains all found devices.| -| `delegate`
[NSObjectHeftDiscoveryDelegate] | Key for value in mpedInfo| -| `version`
*NSString* | Current HeftManager version.| - -**Code example** - -````objectivec -// Create a manager on view load -- (void)viewDidLoad{ - [super viewDidLoad]; - HeftManager* manager = [HeftManager sharedManager]; - manager.delegate = self; - [manager resetDevices]; // Clean out device list -} -```` - -**Methods** - -[**Start Discovery**](#29) -*** -- (void)startDiscovery; - -[**Shared Manager**](#30) -*** -+ (HeftManager*)sharedManager; - -[**Client for device (NSString)**](#31) -*** -- (void)clientForDevice:(HeftRemoteDevice *)device sharedSecret:(NSString *)sharedSecret delegate:(NSObject HeftStatusReportDelegate*)delegate; - -### HeftClient{#22} - -`HeftClient` - -High level interface for Headstart API. HeftClient handles the communication between the mPos app and the card reader. The HeftClient object also stores information about it's card reader device in the mpedInfo dictionary. Device Log operations are also implemented in HeftClient. To create a new HeftClient object the clientForDevice method is called from an instance of the HeftManager. Transaction and log requests (and the acceptSignature response) are done by calling HeftClient methods with the relevant input. The library reports the status of the requests by calling delegates of the HeftStatusReportDelegate protocol. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `sharedSecret`
[NSString] | The shared secret is a key provided by Handpoint when you get your account that enables you to perform live operations with the card reader. However, if you're developing with a starter kit, the test shared secret is specified in the example.| -| `mpedInfo`
[NSDictionary] | Dictionary with card reader info details, obtained by querying it from device on interface creation.| -| `isTransactionResultPending`
[BOOL] | Indicates whether a transaction result is pending on the card reader.| -| | **Note: A pending transaction result is retained by the card reader if a disconnect occurs between card reader and app before the transaction result can be delivered during a SALE, REFUND or VOID processing.**| -| `kSerialNumberInfoKey`
[NSString constant ] | Key for value in mpedInfo| -| `kPublicKeyVersionInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kEMVParamVersionInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kGeneralParamInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kManufacturerCodeInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kModelCodeInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kAppNameInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kAppVersionInfoKey`
[NSString Constant ] | Key for value in mpedInfo| -| `kXMLDetailsInfoKey`
[NSString Constant ] | Key for value in mpedInfo| - - -**Code example** - -````objectivec -//clientForDevice:sharedSecret:delegate: -//Creates a HeftClient object(connection to device) --(void)connectToFirstCardReaderWith:(NSData*)sharedSecret; -{ - //Try to connect to first device in devices array - [heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecret:sharedSecret delegate:self]; - //Client calls the didConnect delegate function if successful -} - -//.... - -//didConnect: -//Called when a connection to specified device was created. --(void)didConnect:(id)client -{ - // connected successfully to a device - // assigne the client to our heftClient property - heftClient = client; -} - -// ..... - -// Do one sale later in code -[heftClient saleWithAmount:1000 currency:@"GBP" cardholder:YES]; -```` - -**Methods** - -[**cancel**](#32) -*** -- (void)cancel; - -[**saleWithAmount**](#2) -*** -- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present; - -[**saleWithAmount**](#2) -*** -- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference; - -[**saleWithAmount**](#2) -*** -- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference; - -[**refundWithAmount**](#5) -*** -- (BOOL)refundWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present; - -[**refundWithAmount**](#5) -*** -- (BOOL)refundWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference; - -[**saleVoidWithAmount**](#3) -*** -- (BOOL)saleVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction; - -[**refundVoidWithAmount**](#3) -*** -- (BOOL)refundVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction; - -[**retrievePendingTransaction**](#8) -*** -- (BOOL)retrievePendingTransaction; - -[**enableScanner**](#36) -*** -- (BOOL)retrievePendingTransaction; - -[**enableScannerWithMultiScan**] -*** -- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan; - -[**enableScannerWithMultiScan**] -*** -- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan buttonMode:(BOOL)buttonMode; - -[**enableScannerWithMultiScan**] -*** -- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan buttonMode:(BOOL)buttonMode timeoutSeconds:(NSInteger)timeoutSeconds; - -[**Disable scanner**](#37) -*** -- (BOOL)disableScanner; - -[**financeStartOfDay**] -*** -- (BOOL)financeStartOfDay; - -[**financeEndOfDay**] -*** -- (BOOL)financeEndOfDay; - -[**financeInit**](#47) -*** -- (BOOL)financeInit; - -[**logSetLevel**](#33) -*** -- (BOOL)logSetLevel:(eLogLevel)level; - -[**logReset**](#35) -*** -- (BOOL)logReset; - -[**logGetInfo**](#34) -*** -- (BOOL)logGetInfo; - -[**acceptSignature**](#7) -*** -- (void)acceptSignature:(BOOL)flag; - -[**getEMVConfiguration**](#7) -*** -- (BOOL)getEMVConfiguration; - - -### HeftRemoteDevice{#23} - -`HeftRemoteDevice` - -An object containing a reference to the accessory device which is passed to the HeftClient on creation. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `name`
[NSString] | Name of device| -| `accessory`
[EAAccessory] | The EAAccessory object| -| `address`
[NSString] | Address of device| - - -### HeftDiscoveryDelegate - -`HeftDiscoveryDelegate` - -Notifications sent by the SDK on various events - new available device found, connection lost, connection found, etc - -**Methods** - -[**didDiscoverFinished**](#37) -*** -- (void)didDiscoverFinished; - -[**didFindAccessoryDevice**](#38) -*** -- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice; - -[**didLostAccessoryDevice**](#39) -*** -- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice; - -### HeftStatusReportDelegate - -`HeftStatusReportDelegate` - -Notifications sent by the SDK on various events - connected to device, request signature, response on error etc. - -**Methods** - -[**didConnect**](#20) -*** -- (void)didConnect:(id-HeftClient)client; - -[**responseStatus**](#14) -*** -- (void)responseStatus:(id-ResponseInfo)info; - -[**responseError**](#15) -*** -- (void)responseError:(id-ResponseInfo)info; - -[**responseFinanceStatus**](#16) -*** -- (void)responseFinanceStatus:(id-FinanceResponseInfo)info; - -[**responseLogInfo**](#43) -*** -- (void)responseLogInfo:(id-LogInfo)info; - -[**requestSignature**](#17) -*** -- (void)requestSignature:(NSString*)receipt; - -[**cancelSignature**](#40) -*** -- (void)cancelSignature; - -[**responseRecoveredTransactionStatus**](#44) -*** -- (void)responseRecoveredTransactionStatus:(id-FinanceResponseInfo)info; - -[**responseScannerEvent**](#41) -*** -- (void)responseScannerEvent:(id-ScannerEventResponseInfo)info; - -[**responseScannerDisabled **](#2) -*** -- (void)responseScannerDisabled:(id-ScannerDisabledResponseInfo)info; - -[**responseEMVReport**](#43) -*** -- (void)responseEMVReport:(NSString *)report; - - -### ResponseInfo{#24} - -`ResponseInfo` - -A ResponseInfo object is passed to the ResponseStatus delegate. It contains information from the card reader about the status of the current transaction. There are two properties: status and xml. status is a string and xml is a dictionary. Usually status contains a message descriptive enough to know whats going on and is useful for displaying to user. The xml dictionary contains all elements of the XML formatted data passed from the card reader and has detailed information on the current state of the card reader. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `statusCode`
*int* | A numerical representation of the status.| -| `status`
[*Status as NSString*](#45) | Financial transaction status message.| -| `xml`
[*XML as NSDictionary*](#46) | Feedback with xml details about transaction from the card reader.| - - -### FinanceResponseInfo{#25} - -`FinanceResponseInfo` - -A FinanceResponseInfo is passed to the responseFinanceStatus delegate at the end of transaction. It contains all necessary information needed about the relevant transaction. FinanceResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to authorisedAmount, transactionId and the html formatted receipts. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `financialResult`
*NSInteger* | A numerical representation of a financial status result. **Status** **Value** EFT_FINANC_STATUS_UNDEFINED 0x00 EFT_FINANC_STATUS_TRANS_APPROVED 0x01 EFT_FINANC_STATUS_TRANS_DECLINED 0x02 EFT_FINANC_STATUS_TRANS_PROCESSED 0x03 EFT_FINANC_STATUS_TRANS_NOT_PROCESSED 0x04 EFT_FINANC_STATUS_TRANS_CANCELLED 0x05| -| `isRestarting`
[*BOOL*] | Indicates whether the card reader is about to restart or not (usually indicated after a software update was received on the card reader).If a restart is indicated then you have 2 seconds to start fetching the logs (before the card reader restarts).After fetching the logs you should disconnect from the card reader and wait for it to be visible again.| -| `authorisedAmount`
*NSInteger* | In the smallest unit for the given CurrencyCode - for the transaction. ISO 4217 defines number of digits in fractional part of currency for every currency code. Example 1000 in the case where CurrencyCode is "0826" (GBP) the amount would be 10.00 pounds or 1000 pense.| -| `transactionId`
[*NSString*] | The id of current transaction.| -| `customerReceipt`
[*NSString*] | Customer receipt in html format.| -| `merchantReceipt`
[*NSString*] | Merchant receipt in html format.| -| `statusMessage`
[*NSString*] | A human readable message describing the result of the transaction.| -| `type`
[*NSString*] | The transaction type represents which type of transaction was done. "SALE" for example.| -| `finStatus`
[*NSString*] | The financial status describes the conclusion of the transaction as received from the card reader. "AUTHORISED" for example.| -| `requestedAmount`
[*NSString*] | The requested amount is the payment amount sent in the original request to the card reader, i.e. the amount which was to charge the card with.| -| `gratuityAmount`
[*NSString*] | The gratuity amount is an additional amount added to the requested payment amount which represents additional fee added to the requested amount. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. The customer inputs an additional amount as a tip, lets say 100. The card is then charged for the requested amount, 1000, as well as the additional gratuity amount, 100. The result will be that the card will be charged for 1100. A calculated gratuity percentage will also be returned.| -| `gratuityPercentage`
[*NSString*] | The gratuity percentage is used to calculate an additional amount to the requested amount. The card reader calculates that amount, rounded up to the closest whole number. This is used when the card reader is supporting the tipping functionality. An example: A sale is started with the amount 1000 and the card reader is set to support tipping. The card reader asks if a tip should be applied by the customer. Instead of the customer adding a value he selects the percentage of the requested amount to be applied as a tip, lets say 10%. The card is then charged for the requested amount, 1000, as well as the additional gratuity percentage, 10%. The result will be that the card will be charged for 1100. A calculated gratuity amount will also be returned.| -| `totalAmount`
[*NSString*] | 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.| -| `currency`
[*NSString*] | The currency used in this transaction.| -| `eFTTransactionID`
[*NSString*] | The EFT (electronic funds transfer) transaction id is a unique GUID from the servers which is linked to this transaction in order to search for a particual transaction. This id is used if a transaction is to be reversed.| -| `originalEFTTransactionID`
[*NSString*] | The original EFT (electronic funds transfer) transaction id is a unique GUID previously received from the servers in order to reverse a transaction. This id is sent with the new eFTTransactionID in order to reference the original transaction. An example: A transaction is made. An eFTTransactionID is received. That transaction has to be reversed. A new transaction is started, now a reverse transaction, with the previously received eFTTransactionID as a parameter in the transaction. In the end result there will be a new eFTTransactionID, for the reverse transaction, and an originalEFTTransactionID referencing the original transaction.| -| `eFTTimestamp`
[*NSString*] | The eFTTimestamp represents the time when the transaction was done. This time is set by the device communicating to the card reader when the connection is established to the card reader.| -| `authorisationCode`
[*NSString*] | If the transaction was authorised the value represented can be used to search for a transaction in our system.| -| `verificationMethod`
[*NSString*] | The verification method represents the card holder verification method used to allow the payment. "PIN" for an example.| -| `cardEntryType`
[*NSString*] | The card entry type is the method the card information was input to card reader. "ICC" for an example represents "Integrated Circuit Card" i.e. the information was read from the chip of the card.| -| `cardSchemeName`
[*NSString*] | The scheme which was used when the transaction was made. (VISA, Mastercard, etc...)| -| `errorMessage`
[*NSString*] | If there was an error during the transaction it is represented here in a human readable text.| -| `customerReference`
[*NSString*] | If a customer reference was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The customer reference can be used to reference in internal systems.| -| `budgetNumber`
[*NSString*] | If a budget number was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The budget number can be used to split payments over a period of months.| -| `recoveredTransaction`
[*NSString*] | This flag is true if the transaction result is from a previous transaction which failed to get sent from the card reader, false otherwise. In the case that the communication between the device and the card reader breaks down, the card reader will attempt to send the result of the previous transaction as an immediate reply when the next transaction is started. If this happens the transaction is flagged as a "RecoveredTransaction". This should be displayed very well in the UI since this is *NOT* the result from the transaction just started.| -| `cardTypeId`
[*NSString*] | The card type id is an identifier inside the Handpoint gateway which represents what kind of card was used. "U015" for an example represents SAS Airline-Systems in our systems.| -| `chipTransactionReport`
[*NSString*] | If present, a full EMV report by the card reader on the Card and Terminal involved in the transaction.| -| `deviceStatus`
[*NSString*] | Gets the device status.| -| `dueAmount`
[*NSString*] | If there's still a part of the amount to be paid.| -| `balance`
[*NSString*] | The balance of the Cardholder's cards if the bank/acquirer supports it.| -| `CardToken`
[*String*] | Gets the card token if it's available, null otherwise.| - - -### ScannerEventResponseInfo{#26} - -`ScannerEventResponseInfo` - -A ScannerEventResponseInfo is passed to the responseScannerEvent delegate during scanner mode when a scan is detected. It contains all necessary information needed about the relevant operation. ScannerEventResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to scanCode string. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `statusCode`
*int* | A numerical representation of the status.| -| `status`
[*Status as NSString*](#45) | Financial transaction status message.| -| `xml`
[*XML as NSDictionary*](#46) | Feedback with xml details about transaction from the card reader.| -| `scanCode`
*NSString* | The code that was scanned.| - -### ScannerDisabledResponseInfo{#27} - -`ScannerDisabledResponseInfo` - -The info object contains information about the scanner operation. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `statusCode`
*int* | A numerical representation of the status.| -| `status`
[*Status as NSString*](#45) | Financial transaction status message.| -| `xml`
[*XML as NSDictionary*](#46) | Feedback with xml details about transaction from the card reader.| - -### LogInfo{#28} - -`LogInfo` - -A LogInfo object is passed to the ResponseLogInfo delegate when logs have been downloaded from the card reader. - -**Properties** - -| Property | Description | -| ----------- | ----------- | -| `statusCode`
*int* | A numerical representation of the status.| -| `status`
[*Status as NSString*](#45) | Financial transaction status message.| -| `xml`
[*XML as NSDictionary*](#46) | Feedback with xml details about transaction from the card reader.| -| `log`
*NSString* | String containing the logging information.| - -### eLogLevel{#13} - -`eLogLevel` - -An enum describing the different levels of logging used in the SDK and in the device. - -**Possible values** - -`eLogNone` `eLogError` `eLogInfo` `eLogFull` `eLogDebug` - -### Transaction Details{#46} - -`XML as NSDictionary` - -The contents of the xml property depend on which type of operation the card reader is responding to. Listed below are all possible keys in the dictionary. Note that not all fields are included all the time. - -### Dictionary keys: - -**StatusMessage** -*** -A human readable description for the returned Status. - -**TransactionType** -*** -The type of transaction performed: UNDEFINED, SALE, VOID_SALE, REFUND, VOID_REFUND, CANCEL_SALE, CANCEL_REFUND - -**FinancialStatus** -*** -The result of the transaction: UNDEFINED, APPROVED, DECLINED, PROCESSED, FAILED, CANCELLED - -Description of the different financial statuses: - -| Parameter | Notes | -| ----------- | ----------- | -| `UNDEFINED`
| Any Financial Status other than the below mentioned financial statuses will be `UNDEFINED`. UNDEFINED means that the SDK couldn't get a response from the Gateway. An automatic cancellation service will try to cancel the transaction in case it was approved. | -| `AUTHORISED`
| The transaction (Sale, Refund,...) has been authorised. Consider this value as "successful". | -| `DECLINED`
| The transaction has been declined by the acquirer or issuer. | -| `PROCESSED`
| The `update` operation was successful.| -| `FAILED`
| Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to `FAILED`. | -| `CANCELLED`
| The transaction has been cancelled. For example if the `stopCurrentTransaction` operation has been used or the cancel button on the terminal has been pressed. | -| `PARTIAL_APPROVAL`
| A partial approval is the ability to partially authorize a transaction if the cardholder does not have the funds to cover the entire cost on their card. The merchant can obtain the remainder of the purchase amount in another form of payment. `PARTIAL_APPROVAL` is **only** applicable to the United States market. | - - -**RequestedAmount** -*** -The amount requested by the POS, as requested by the POS (i.e. no decimal point). - -**GratuityAmount** -*** -The gratuity amount entered by the cardholder, if any. - -**GratuityPercentage** -*** -The gratuity amount, as a percentage of the requested amount. - -**TotalAmount** -*** -The total of the gratuity and requested amount. - -**TransactionID** -*** -The transaction number used for this transaction, as maintained by the Eft Client. - -**EFTTransactionID** -*** -The EFT reference, given by the system, to make the transaction unique. - -**OriginalEFTTransactionID** -*** -The original EFT reference, given by the POS, as part of a VOID_SALE or a VOID_REFUND transaction. - -**EFTTimestamp** -*** -The date and time of the transaction, in ISO format (YYYYMMDDHHmmSS). - -**AuthorisationCode** -*** -The transaction authorization code, as given by the system. - -**CVM** -*** -The Cardholder Verfication Method: UNDEFINED, SIGNATURE, PIN, PIN_SIGNATURE, FAILED, NOT_REQUIRED - -**CardEntryType** -*** -The card data acquisition type: UNDEFINED, MSR, ICC, CNP - -**CardSchemeName** -*** -The card, reported, scheme name. - -**CardTypeId** -*** -The ID of the Card Type. - -**SerialNumber** -*** -The serial number of the PED. - -**BatteryStatus** -*** -A number, followed by the % sign, which indicates current charge level of the battery. - -**BatterymV** -*** -An integer, which represent the batter charge, in mV. - -**BatteryCharging** -*** -Indicates whether the battery is charging, or not. Values are true or false. - -**ExternalPower** -*** -Indicates whether the PED is connected to an external power source (e.g. a AC adapter). Values are true or false. - -**ApplicationName** -*** -The name of the application running on the PED. - -**ApplicationVersion** -*** -A version string of the form major.minor.build”(e.g. 1.2.118). - -**ErrorMessage** -*** -Description of the error, if any. - -**RecoveredTransaction** -*** -Indicates that the transaction result is a recovered transaction. The key is only included if value is true. - -### CmdIds - -`card reader Status messages` - -Status messages received from card reader: - -### Possible values - -`EFT_PP_STATUS_SUCCESS` -`EFT_PP_STATUS_INVALID_DATA` -`EFT_PP_STATUS_PROCESSING_ERROR` -`EFT_PP_STATUS_COMMAND_NOT_ALLOWED` -`EFT_PP_STATUS_NOT_INITIALISED` -`EFT_PP_STATUS_CONNECT_TIMEOUT` -`EFT_PP_STATUS_CONNECT_ERROR` -`EFT_PP_STATUS_SENDING_ERROR` -`EFT_PP_STATUS_RECEIVING_ERROR` -`EFT_PP_STATUS_NO_DATA_AVAILABLE` -`EFT_PP_STATUS_TRANS_NOT_ALLOWED` -`EFT_PP_STATUS_UNSUPPORTED_CURRENCY` -`EFT_PP_STATUS_NO_HOST_AVAILABLE` -`EFT_PP_STATUS_CARD_READER_ERROR` -`EFT_PP_STATUS_CARD_READING_FAILED` -`EFT_PP_STATUS_INVALID_CARD` -`EFT_PP_STATUS_INPUT_TIMEOUT` -`EFT_PP_STATUS_USER_CANCELLED` -`EFT_PP_STATUS_INVALID_SIGNATURE` -`EFT_PP_STATUS_WAITING_CARD` -`EFT_PP_STATUS_CARD_INSERTED` -`EFT_PP_STATUS_APPLICATION_SELECTION` -`EFT_PP_STATUS_APPLICATION_CONFIRMATION` -`EFT_PP_STATUS_AMOUNT_VALIDATION` -`EFT_PP_STATUS_PIN_INPUT` -`EFT_PP_STATUS_MANUAL_CARD_INPUT` -`EFT_PP_STATUS_WAITING_CARD_REMOVAL` -`EFT_PP_STATUS_TIP_INPUT` -`EFT_PP_STATUS_SHARED_SECRET_INVALID` -`EFT_PP_STATUS_SHARED_SECRET_AUTH` -`EFT_PP_STATUS_WAITING_SIGNATURE` -`EFT_PP_STATUS_CONNECTING` -`EFT_PP_STATUS_SENDING` -`EFT_PP_STATUS_RECEIVEING` -`EFT_PP_STATUS_DISCONNECTING` -`EFT_PP_STATUS_PIN_INPUT_COMPLETED` -`EFT_PP_STATUS_POS_CANCELLED` -`EFT_PP_STATUS_REQUEST_INVALID` -`EFT_PP_STATUS_CARD_CANCELLED` -`EFT_PP_STATUS_CARD_BLOCKED` -`EFT_PP_STATUS_REQUEST_AUTH_TIMEOUT` -`EFT_PP_STATUS_REQUEST_PAYMENT_TIMEOUT` -`EFT_PP_STATUS_RESPONSE_AUTH_TIMEOUT` -`EFT_PP_STATUS_RESPONSE_PAYMENT_TIMEOUT` -`EFT_PP_STATUS_ICC_CARD_SWIPED` -`EFT_PP_STATUS_REMOVE_CARD` -`EFT_PP_STATUS_SCANNER_IS_NOT_SUPPORTED` -`EFT_PP_STATUS_SCANNER_EVENT` -`EFT_PP_STATUS_BATTERY_TOO_LOW` -`EFT_PP_STATUS_ACCOUNT_TYPE_SELECTION` -`EFT_PP_STATUS_BT_IS_NOT_SUPPORTED` -`EFT_PP_STATUS_PAYMENT_CODE_SELECTION` -`EFT_PP_STATUS_PARTIAL_APPROVAL` -`EFT_PP_STATUS_AMOUNT_DUE_VALIDATION` -`EFT_PP_STATUS_INVALID_URL` -`EFT_PP_STATUS_WAITING_CUSTOMER_RECEIPT` -`EFT_PP_STATUS_PRINTING_MERCHANT_RECEIPT` -`EFT_PP_STATUS_PRINTING_CUSTOMER_RECEIPT` -`EFT_PP_STATUS_WAITING_HOST_MSG_TO_HOST` -`EFT_PP_STATUS_WAITING_HOST_MSG_RESP` -`EFT_PP_STATUS_INITIALISATION_COMPLETE` - - -### Status strings{#45} - -`Status as NSString` - -An NSString containing the status message - can be one of the following: - -### Possible values - -`Success` -`Invalid data` -`Processing error` -`Not allowed` -`Not initialized` -`Connect timeout` -`Connect error` -`Sending error` -`Receiveing error` -`No data available` -`Transaction not allowed` -`Unsupported currency` -`No host available` -`Card reader error` -`Card reading failed` -`Invalid card` -`Input timeout` -`User cancelled` -`Invalid signature` -`Waiting card` -`Card inserted` -`Application selection` -`Application confirmation` -`Amount validation` -`PIN input` -`Manual card input` -`Waiting card removal` -`Tip input` -`Shared secret invalid` -`Connecting` -`Sending` -`Receiving` -`Disconnecting` -`PIN entry completed` -`Merchant cancelled the transaction` -`Request invalid` -`Card cancelled the transaction` -`Blocked card` -`Request for authorisation timed out` -`Request for payment timed out` -`Response to authorisation request timed out` -`Response to payment request timed out` -`Please insert card in chip reader` -`Remove the card from the reader` -`This device does not have a scanner` -`Scanner is not supported` -`Scanner event` - -## Process details - -The following table contains result codes that can occur in the COMMAND response STATUS field (see section 1.3 above). - -In addition the following table contains the text information presented in the StatusMessage field that is part of the FinancialTransactionResponse Xml response object. - -All values are in hex in the following table. - -| Status ID | Value | StatusMessage| Details | -| ----------- | ----------- |----------- | ----------- | -| EFT_SUCCESS | 0001| One of the following: "" (an empty string) "AUTH CODE #" "REFUND ACCEPTED" "REVERSAL ACCEPTED"|Operation completed successfully. No further actions required.| -| EFT_INVALID_DATA | 0002|"Invalid data"|Invalid COMMAND request object, from the POS App, at the start of an operation. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.| -|EFT_PROCESSING_ERROR |0003| "Processing error"| An unexpected error occurred during processing. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.| -|EFT_COMMAND_NOT_ALLOWED| 0004| "Command not allowed"| The card reader is currently busy processing another command. Please retry the operation once the current operation has completed.|| -|EFT_NOT_INITIALISED |0005 |"Device is not initialized"| The current operation can’t be completed because there is a pending software update that must be applied before processing can continue. Please retry the operation after the card reader has restarted itself.| -|EFT_CONNECT_TIMEOUT |0006 |"Connection time out detected"| The back end connection timed out during an update. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.| -|EFT_CONNECT_ERROR |0007 |"Connection error" |It was not possible to establish a connection to the back end system during an update operation. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.| -|EFT_SENDING_ERROR |0008 |"Send error" |A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Note: You may be asked to provide the card reader logs. Once verified please retry the operation.| -|EFT_RECEIVING_ERROR |0009| "Receiving error"| A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Note: You may be asked to provide the card reader logs. Once verified please retry the operation.| -|EFT_NO_DATA_AVAILABLE |000A| "No data available"| The POS App is trying to fetch the card reader log file but there is no data stored in the log file. If logs are required then please set the log level to an appropriate value and retry the operation.| -|EFT_TRANS_NOT_ALLOWED |000B| "Transaction not allowed"| `Currently not used`| -|EFT_UNSUPPORTED_CURRENCY| 000C| "Currency not supported"| A currency has been selected that the card reader has not been configured for. Please select the correct currency and retry the operation. Alternatively, please contact technical support and ask for the specific currency to be supported.| -|EFT_NO_HOST_AVAILABLE| 000D |"No host configuration found"| An update was initiated but the card reader could not find any host information for the back end system, even though it otherwise contains valid configuration. This is indicative of an invalid `hostBlock` block with in the `HostList` block in this device configuration, which was placed on the card reader during a previous update. Please contact technical support and provide card reader logs and ask for a replacement device. The card reader will be unable to update itself and must be replaced.| -|EFT_CARD_READER_ERROR |000E |"Card reader error"| Error detected in the chip reader or the magnetic stripe reader. Please retry the operation. If the issue persists please contact technical support and provide them with the card reader logs as well as asking for a replacement reader.| -|EFT_CARD_READING_FAILED| 000F| "Failed to read card data"| The card reader could not read any data from the card. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.| -|EFT_INVALID_CARD |0010 |"INVALID CARD" |The card reader detected invalid card data. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.| -|EFT_INPUT_TIMEOUT |0011| "Timeout waiting for user input"| The card reader timed out while waiting for a user action. No further actions required.| -|EFT_USER_CANCELLED |0012| "TRANSACTION VOID" "User cancelled the transaction" |The current operation was cancelled by card holder. No further actions required.| -|EFT_SHARED_SECRET_INVALID| 001D| "Shared Secret invalid"| The card reader believes that the POS App has an incorrect shared secret. No financial operations will be possible (e.g. SALE, REFUND). Please type the correct shared secret into the POS App or contact technical support for further assistance.| -|EFT_SHARED_SECRET_AUTH |001E |"Authenticating POS"| The card reader is about to challenge the POS App for a correct shared secret. No further actions are required.| - | REPORT STATUS SPECIFIC| -|EFT_INVALID_SIGNATURE |0013| "TRANSACTION VOID"| The merchant indicated that the signature provided by the card holder was invalid. No further actions are required.| -|EFT_WAITING_CARD |0014| "Waiting for card" |The card reader is waiting for a card to be inserted into the chip reader or for a card to be swiped (only applies to card readers with external MSR). Insert or swipe a card to continue with the transaction.| -|EFT_CARD_INSERTED |0015| "Card detected" |`Currently not used`| -|EFT_APPLICATION_SELECTION |0016| "Waiting for application selection" |The card reader is waiting for the card holder to select a card application to be used for the transaction. The card holder must select an application for use (e.g. VISA, MASTERCARD, etc.) and should then press either the OK button to continue. Press the C/Cancel button to abort the transaction.| -|EFT_APPLICATION_CONFIRMATION| 0017| "Waiting for application confirmation"| The card reader is waiting for the card holder to confirm that the displayed card application should be used for the transaction. The card holder should press either the OK or the C/Cancel button.| -|EFT_AMOUNT_VALIDATION| 0018 |"Waiting for amount validation"| The card reader is waiting for the card holder to confirm that the amount presented is correct. The card holder should press either the OK or the C/Cancel button.| -|EFT_PIN_INPUT |0019| "Waiting for PIN entry"| The card reader is waiting for the card holder to enter his/her PIN. The card holder should enter his PIN and then press the OK button to continue. For PIN bypass press the OK button without entering any PIN digits (this will trigger signature fallback). Press the C/Cancel button to abort the transaction. Note: It is not possible to cancel this operation from the POS App.| -|EFT_MANUAL_CARD_INPUT |001A| "Waiting for manual card data"| `Currently not used`| -|EFT_WAITING_CARD_REMOVAL| 001B| "Waiting for card removal"| A card was detected in the card reader at the start of a transaction, presumably left there from a previous transaction. Please remove the card and restart the operation.| -|EFT_TIP_INPUT |001C| "Waiting for gratuity" |The card reader is waiting for the card holder to enter/confirm tip/gratuity information.| -|EFT_WAITING_SIGNATURE |001F| "Waiting for signature" |The card reader is waiting for confirmation from the merchant that the card holder signature is valid. The merchant should press either the Accepted or Declined/Cancel in the POS App. Pressing Cancel or OK on the card reader will not have any effect.| -|EFT_WAITING_HOST_CONNECT |0020| "Connecting to host"| The card reader is establishing a connection to the back end system. No further actions are required.| -|EFT_WAITING_HOST_SEND| 0021 |"Sending data to host" |The card reader is sending data to the back end system. No further actions are required.| -|EFT_WAITING_HOST_RECEIVE| 0022| "Waiting for data from host" |The card reader is waiting for data from to the back end system. No further actions are required.| -|EFT_WAITING_HOST_DISCONNECT| 0023| "Disconnecting from host"| The card reader is disconnecting from the back end system. No further actions are required.| -|EFT_PIN_INPUT_COMPLETED| 0024| "PIN entry completed"| PIN entry has been completed. No further actions required.| -|EFT_POS_CANCELLED |0025| "TRANSACTION VOID" |The current operation was cancelled by merchant. No further actions required.| -|EFT_REQUEST_INVALID| 0026| "Request invalid"| Card not allowed with this transaction type.| -|EFT_CARD_CANCELLED |0027| "TRANSACTION VOID"| The chip on the card cancelled the transaction. No further actions required.| -|EFT_CARD_BLOCKED |0028| |"CARD BLOCKED" |The card used in the transaction is blocked. Please retry the transaction with a non-blocked card.| -|EFT_REQUEST_AUTH_TIMEOUT |0029| "Request for authorisation timed out"| Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.| -|EFT_REQUEST_PAYMENT_TIMEOUT| 002A| "Request for payment timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.| -|EFT_RESPONSE_AUTH_TIMEOUT |002B| "Response to authorisation request timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.| -|EFT_RESPONSE_PAYMENT_TIMEOUT| 002C| "Response to payment request timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. You MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Note: You may be asked to provide the card reader logs. Once you have verified that the transaction did not go through then please make sure the phone/pc has an internet connection and then retry the operation.| -|EFT_ICC_CARD_SWIPED| 002D| "Please insert card in chip reader" |`Currently not used`| -|EFT_REMOVE_CARD |002E| "Remove the card from the reader" |`Currently not used`| -|EFT_SCANNER_IS_NOT_SUPPORTED| 002F| "This device does not have a scanner" |Bar-code scanner hardware is not present on this card reader. No further actions are required.| -|EFT_SCANNER_EVENT| 0030| "" |Bar-code data was just read with the bar-code scanner and returned to the POS App. No further actions are required.| -|EFT_BATTERY_TOO_LOW| 0031| "Operation cancelled, the battery is too low. Please charge."| An operation was started, but the battery charge level is too low to complete the operation. Please recharge the card reader.| -|EFT_ACCOUNT_TYPE_SELECTION| 0032| "Waiting for account type selection"| The card reader is waiting for the card holder to choose an account type for the transaction (i.e. default, credit, cheque/debit or savings).| \ No newline at end of file diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosdevicemanagement.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosdevicemanagement.md index 98f35b7..2b3b8eb 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosdevicemanagement.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosdevicemanagement.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 id: iosdevicemanagement --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosevents.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosevents.md index 3cadb49..a50716c 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosevents.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosevents.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 id: iosevents --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosinstallation.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosinstallation.md index 4310562..9c7560b 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosinstallation.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosinstallation.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 id: iosinstallation --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosintegration.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosintegration.md index 1b6f84f..c913b26 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosintegration.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosintegration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 id: iosintegration --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosmigration.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosmigration.md index e4f5879..d99260b 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosmigration.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosmigration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 id: iosmigration --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosobjects.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosobjects.md index 9f54d5e..f603e39 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosobjects.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosobjects.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 id: iosobjects --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosprocessing.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosprocessing.md index 6d32c3e..ea2885b 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iosprocessing.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosprocessing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 id: iosprocessing --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iosreleasenotes.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iosreleasenotes.md new file mode 100644 index 0000000..c595b19 --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iosreleasenotes.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 2 +id: iosreleasenotes +--- + + + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 4.0.1 +**Fixes**: + - Multi MID fix for INTERAC and POSTBRIDGE acquirers. + +## 4.0.0 +**Features**: + - Support for Multi MID and HiPro scanner fixes. + diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iossdkprocessing.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iossdkprocessing.md index f754bb5..b614ac1 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iossdkprocessing.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iossdkprocessing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 id: iossdkprocessing --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.1/iostransactions.md b/ios_versioned_docs/version-iOS SDK 4.0.1/iostransactions.md index b88e917..c042a85 100644 --- a/ios_versioned_docs/version-iOS SDK 4.0.1/iostransactions.md +++ b/ios_versioned_docs/version-iOS SDK 4.0.1/iostransactions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 id: iostransactions --- diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosdevicemanagement.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosdevicemanagement.md new file mode 100644 index 0000000..2b3b8eb --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosdevicemanagement.md @@ -0,0 +1,313 @@ +--- +sidebar_position: 9 +id: iosdevicemanagement +--- + + + +# Terminal Management + +## Update terminal{#47} + +`financeInit` Method + +The update operation checks for available software or configuration update for the payment terminal and initiates a download if needed. + +**Code example** + +````objectivec +//financeInit +//Initializes the card reader and updates config. +-(IBAction)updateCardReader +{ + [heftClient financeInit]; +} +```` + +**Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| This method always returns YES| + +## Shared Manager{#11} + +`sharedManager` Method + +Provides access to the heftManager. The heft manager is used for discovering devices and creating a HeftClient with a connection to selected payment terminals. + +**Code example** + +````objectivec +//SharedManager +//Provides access to the heftManager + +//Create an instance of the shared manager at set it's delegate +HeftManager* heftManager = [HeftManager sharedManager]; +heftManager.delegate = self; +```` + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| [**HeftManager**](iosobjects.md#19)| The heftManager instance| + + + + + +## Client for device (NSString){#12} + +`clientForDevice` Method + +Creates a HeftClient object. If a connection is successful, the HeftClient object is returned in the didConnect event. All transactions are done using the heftClient. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
*NSInteger* | The payment terminal to connect to.| +| `sharedSecret` Required
*NSString* | Shared secret only known by the merchant and Handpoint.| +| `aDelegate` Required
*BOOL* | The HeftStatusReportDelegate for the HeftClient to report to.| + + +**Code example** + +````objectivec +//clientForDevice:sharedSecretString:delegate: +//Creates a HeftClient object(connection to device) +NSString* sharedSecret = @"0102030405060708091011121314151617181920212223242526272829303132"; +-(void)connectToFirstCardReaderWith:(NSString*)sharedSecret; +{ + //Try to connect to the first payment terminal in the array + [heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecretString:sharedSecret delegate:self]; + //Client calls the didConnect delegate function if successful +} +```` + +**Events invoked** + +[**didConnect**](iosevents.md#20) + +Called when a connection to specified device was created. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| YES if operation starts successfully| + + + + +## Start Discovery {#32} + +`startDiscovery` Method + +Displays a list of available accessory devices in a modal window. + +**Code example** + +````objectivec +//startDiscovery +//Starts the BT discovery process +-(void)startDiscovery; +{ + [heftManager startDiscovery]; + //Start search activity indicator or other desired functions +} +```` + +## Set log level{#33} + +`logSetLevel` Method + +Sets the log level of the payment terminal. There are four levels of logging: none, info, full, debug. Setting the log level means that relevant information concerning the application operation will be stored. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `level` Required
[eLogLevel](iosobjects.md#13) | eLogLevel available types: eLogNone, eLogInfo, eLogFull, eLogDebug| + +**Code example** + +````objectivec +//logSetLevel: +//Sets the log level of the card reader. +-(void)disableCardReaderLogs +{ + [heftClient logSetLevel:eLogNone]; +} +-(void)enableCardReaderDebugLogs +{ + [heftClient logSetLevel:eLogDebug]; +} +```` + +**Returns** + + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| This method always returns YES| + + + + + + +## Fetch logs{#34} + +`logGetInfo` Method + +Retrieves the logging info. Returns them in the responseLogInfo event. + +**Code example** + +````objectivec +//logGetInfo +//Retrieves the logging info. +-(void)getLogsFromCardReader +{ + [heftClient logGetInfo]; +} +```` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| This method always returns YES| + +## Reset logs{#35} + +`logReset` Method + +Clears the logging information stored so far. + +**Code example** + +````objectivec +//logReset +//Clears the logging information stored so far +-(void)clearLogs +{ + [heftClient logReset]; +} +```` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| This method always returns YES| + +## Enable scanner{#36} + +`enableScanner` Method + +Switches the payment terminal in scan mode. Only if the card reader supports it. To cancel/stop scan mode, call the cancel method of the heft client. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `multiScan`
*Boolean* | Yes [default] to activate multiScan mode.
No to activate singleScan mode.

Multi-scan mode allows the user to scan until the scan operation is canceled, or a timeout occurs, single-scan mode is active until one scan has occurred then it disables the scan mode.| +| `buttonMode`
*Boolean* | Yes [default] if buttonMode is on.
No otherwise.

If button mode is on then the operator needs to press the scan button to activate the scanner (during scan mode).| +| `timeoutSeconds`
*NSInteger* | 0 [default] - The payment terminal will determine when scanning should time out.
x - the scanner will time out if x seconds of inactivity occur.| + +**Code example** + +````objectivec +//enableScanner:multiScan:buttonMode:timeoutSeconds +//Places the card reader in a scan only mode. +//To cancel/stop scan mode call cancel function. +-(IBAction)startScan +{ + [heftClient enableScanner]; +} +-(IBAction)startMultiScan +{ + [heftClient enableScannerWithMultiScan:YES]; +} +```` + +**Events invoked** + +[**responseScannerEvent**](iosevents.md#41) + +Called to inform that a scan has been performed, several calls can be expected. The info object contains scanCode, status and a dictionary (xml). + +## Disable scanner + +`disableScanner` Method + +Disables the scanner, if possible. + +**Code example** + +````objectivec +//disableScanner +//Disable the scanner + -(IBAction)disableScanner +{ +[heftClient disableScanner]; +} +```` + +**Events invoked** + +[**responseScannerDisabled**](iosevents.md#42) + +Called to inform that a scan has been performed, several calls can be expected. The info object contains scanCode, status and a dictionary (xml). + +## Get SDK version + +`getSDKVersion` Method + +Returns the current SDK version as a string. + +**Code example** + +````objectivec +//getSDKVersion +//Log SDK version number + NSLOG(@"SDK version: %@", [heftManager getSDKVersion]; +```` + +## Get SDK build number + +`getSDKBuildNumber` Method + +Returns the current SDK build as a string. + +**Code example** + +````objectivec +//getSDKBuildNumber +//Log SDK build number + NSLOG(@"SDK build: %@", [heftManager getSDKBuildNumber]; +```` \ No newline at end of file diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosevents.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosevents.md new file mode 100644 index 0000000..a50716c --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosevents.md @@ -0,0 +1,333 @@ +--- +sidebar_position: 10 +id: iosevents +--- + + + +# Events + +### didConnect{#20} + +`didConnect` Method + +Called when a connection to the client has been established through the method clientForDevice. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `client` Required
[HeftClient](iosobjects.md#22) | The client object, used to perform transactions and communicate with the payment terminal.| + +**Code example** + +````objectivec +//didConnect: +//Called when a connection to specified device was created. +-(void)didConnect:(id)client +{ + // connected successfully to a device + // assign the client to our heftClient property + heftClient = client; +} +```` + +### didDiscoverFinished {#37} + +`didDiscoverFinished` Method + +When the modal window from startDiscovery is closed then this event is called. + +**Code example** + +````objectivec +//didDiscoverFinished +// This function gets called when discovery is finished +- (void)didDiscoverFinished; +{ + NSLog(@"Discover finished"); + //Stop search activity indicator or other desired functions +} +```` + + +### didFindAccessoryDevice{#38} + +`didFindAccessoryDevice` Method + +Notifies that a new accessory device was found. When a payment terminal is detected this delegate is called. You can take the newDevice object and create a new heft client for that particular terminal or store it in memory to connect to it later. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `newDevice` Required
[HeftRemoteDevice](iosobjects.md#23) | An object containing a reference to the accessory device.| + +**Code example** + +````objectivec +//didFindAccessoryDevice +//Delegate which notifies that a new accessory device was found. +- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice +{ + NSLog(@"Found new device"); + //Connect to device or store found device for later. +} +```` + + +### didLostAccessoryDevice{#39} + + +`didLostAccessoryDevice` Method + +Notifies that the accessory device was disconnected. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `oldDevice` Required
[HeftRemoteDevice](iosobjects.md#23) | An object containing a reference to the accessory device.| + +**Code example** + +````objectivec +//didLostAccessoryDevice +//Delegate which notifies that an accessory device was disconnected +- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice +{ + NSLog(@"Device disconnected"); + //Remove device from devices array + [heftManager.devicesCopy removeObject:oldDevice]; + //Do some cleanup after disconnecting if necessary + +} +```` + +### responseStatus{#14} + +`responseStatus` Method + +Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about the status of operation. The info object contains a string (status) and a dictionary (xml). + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[ResponseInfo](iosobjects.md#24) | Includes status code, status text and detailed xml.| + +**Code example** + +````objectivec +//responseStatus: +//Called to inform about the status of the transaction +-(void)esponseStatus:(id)info +{ + NSLog(info.status); + NSLog(info.xml.description); +} +```` + +### responseFinanceStatus{#16} + +`responseFinanceStatus` Method + +Notifies that the transaction has completed. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[FinanceResponseInfo](iosobjects.md#25) | Information about current transaction status.| + +**Code example** + +````objectivec +//responseFinanceStatus: +//Called at the end of a transaction to inform about the result of the operation. +-(void)responseFinanceStatus:(id)info +{ + NSLog(info.status); + NSLog(info.customerReceipt); + //print receipts +} +```` + +### responseError{#15} + +`responseError` Method + +Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about the status of operation. The info object contains a string (status) and a dictionary (xml). + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[ResponseInfo](iosobjects.md#24) | The info object contains a string (status) and a dictionary (xml).| + +**Code example** + +````objectivec +//responseError: +//Called when an error happens. +-(void)responseError:(id)info +{ + NSLog(info.status); + NSLog(info.xml.description); +} +```` + +### requestSignature{#17} + +`requestSignature` Method + +Called during a financial operation if a signature from the customer is needed. The requestSignature delegate should be implemented to print out or display the receipt for the customer to sign. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `receipt` Required
*NSString* | The receipt is a html formatted string containing a receipt for the customer to sign.| + +**Code example** + +````objectivec +//requestSignature: +//Is called if a signature from the customer is needed. +-(void)requestSignature:(NSString*)receipt +{ + NSLog(receipt); + //Display buttons to accept or decline customer signature + UIAlertView* alert = [[UIAlertView alloc] initWithTitle:@"" message:@"sign?" delegate:self cancelButtonTitle:@"No" otherButtonTitles:@"Yes", nil]; + [alert show]; +} +```` + +### cancelSignature{#40} + +`cancelSignature` Method + +Called if the signature request times out. If the payment terminal does not receive an approval for the signature within a certain timeframe, it cancels the transaction and sends a notification to the app. + +**Code example** + +````objectivec +//cancelSignature +//Called if the signature request times out. +-(void)cancelSignature +{ + NSLog(@"Signature request timed out"); +} +```` + +### responseScannerEvent{#41} + +`responseScannerEvent` Method + +Called to inform that a scan has been performed, several calls can be expected. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[ScannerEventResponseInfo](iosobjects.md#26) | The info object contains scanCode, status and a dictionary (xml).| + +**Code example** + +````objectivec +//responseScannerEvent: +//Called to inform that a scan has been performed +-(void)responseScannerEvent:(id)info +{ + NSLog(info.scanCode); //barcode scanned + NSLog(info.xml.description); +} +```` + +### responseScannerDisabled{#42} + +`responseScannerDisabled` Method + +Called to notify that the scanner has been disabled. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[ScannerDisabledResponseInfo](iosobjects.md#27) | The info object contains information about the scanner operation.| + +**Code example** + +````objectivec +//responseScannerDisabled: +//Called to notify that the scanner has been disabled. +-(void)responseScannerDisabled:(id)info +{ + NSLog(info.status); +} +```` + +### responseLogInfo{#43} + +`responseLogInfo` Method + +Called when logs have been downloaded from the payment terminal by using the logGetInfo method. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[LogInfo](iosobjects.md#28) | The info object has the string property log which holds the log info in text with carriage returns.| + +**Code example** + +````objectivec +//responseLogInfo: +//Called when logs have been downloaded from the card reader by using the logGetInfo method. +-(void)responseLogInfo:(id)info +{ + NSLog(info.log); + //write to log file +} +```` + +### responseRecoveredTransactionStatus{#44} + +`responseRecoveredTransactionStatus` Method + +Notifies that a transaction has been recovered. + +This method is **OPTIONAL** and only required if retrievePendingTransaction is called. + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `info` Required
[*FinanceResponseInfo*](iosobjects.md#25) | Information about the recovered transaction status.

**If an attempt was made to recover a transaction when none was pending then this parameter WILL be nil.**| + + +**Code example** + +````objectivec +//responseRecoveredTransactionStatus: +//Called when a pending transaction result has been recovered from the payment terminal. +- (void)responseRecoveredTransactionStatus:(id)info{ + if(info != nil) { + if(info.statusCode == EFT_PP_STATUS_SUCCESS) { + NSLog(info.status); + NSLog(info.customerReceipt); + NSLog(info.merchantReceipt); + // print receipts and/or save receipts in the transaction log. + + if(info.financialResult == EFT_FINANC_STATUS_TRANS_APPROVED){ + // Process to recover an authorized transaction result. + } else if(info.financialResult == EFT_FINANC_STATUS_TRANS_DECLINED) { + // Process to recover a declined transaction result. + } + } else if(info.statusCode != EFT_PP_STATUS_NO_DATA_AVAILABLE) { + // some other error was detected while waiting for a pending transaction result. + } + } + // else a pending transaction result was not found. +} +```` diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosinstallation.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosinstallation.md new file mode 100644 index 0000000..9c7560b --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosinstallation.md @@ -0,0 +1,98 @@ +--- +sidebar_position: 5 +id: iosinstallation +--- + + + + +# SDK Installation + + +## CocoaPods + +[CocoaPods](https://cocoapods.org/) is a dependency manager for Cocoa projects. You can install it with the following command: + +```` +$ gem install cocoapods +```` + +If you don't have a `Podfile` yet: + +```` +$ pod init +```` + +To integrate the HandpointSDK into your Xcode project using CocoaPods, specify it in your `Podfile`: + +```` +source 'https://github.com/CocoaPods/Specs.git' +platform :ios, '8.0' +use_frameworks! + +target 'your_target' do + pod 'HandpointSDK', '~> 3.2.3' +end +```` + +Then, run the following command: + +```` +$ pod install +```` + +## Carthage + +[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. + +You can install Carthage with [Homebrew](https://brew.sh/) using the following command: + +``` +$ brew update +$ brew install carthage +``` + +To integrate the HandpointSDK into your Xcode project using Carthage, specify it in your `Cartfile`: + +```` +github "handpoint/HandpointSDK-iOS" +````` + +Run `carthage update` to build the framework and drag the built `HandpointSDK.framework` into your Xcode project. + +## Manually + +If you'd rather handle the dependency manually there are three different approaches to include the ```HandpointSDK``` in your project: + +### Prebuilt static library + +Download the latest pre-built static library from [Github](https://github.com/handpoint/HandpointSDK-iOS) and refer to the readme.md for the installation steps. + +### Building the project yourself + +Download the latest version from the master branch: + +``` +$ git clone https://github.com/handpoint/HandpointSDK-iOS.git +``` + +Alternatively you can add it as a git [submodule](https://git-scm.com/docs/git-submodule): + +``` +$ git submodule add https://github.com/handpoint/HandpointSDK-iOS.git +``` + +### Framework + +You'll find the dynamic framework project called `HandpointSDK.xcodeproj` at the root of the repo. + +### Static Library + +You'll find the static library project called `headstart.xcodeproj` under the `Library` folder. + +We **strongly** discourage you from building this project yourself. + +This project contains several targets, you need to build the aggregated target `device-simulator Release` + +This target produces a .zip file in the same directory as the `headstart.xcodeproj` file containing both the library and the simulator library. + diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosintegration.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosintegration.md new file mode 100644 index 0000000..b42abaf --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosintegration.md @@ -0,0 +1,188 @@ +--- +sidebar_position: 6 +id: iosintegration +--- + + +# Integration Guide + +**The SDK supports the following connection methods:** + +1. **[Bluetooth (HiLite)](#filesiniOSSDK)** +2. **[Lightning (HiPro)](#filesiniOSSDK)** + +## Files in iOS SDK {#filesiniOSSDK} + +### If you're using the library/Cocoapods: + +- **HandpointAll.h**: #import this header file into your classes. +- **libheft.a**: The SDK library. + +### If you're using the framework/Carthage: + +- ** HandpointSDK.h**: #import this header file into your classes. +- **HandpointSDK.framework**: The SDK library. + +The SDK also includes a simulator, a library configured to simulate a payment terminal - intended for early development of an user interface. To use it, just link the libheft.a file in the HeftSimulatorLibrary folder, instead of the actual SDK library. + +## Development settings for the SDK + +- **Dependencies**:The Heft library depends on the``` ExternalAccessory``` and ``` libc++.dylib``` frameworks included with the iOS SDK. These frameworks and the **libheft.a** SDK library itself need to be linked to your project for the Handpoint interface to work properly. + +- **Communication protocol**: Your application needs to support the card reader communication protocol. For this reason, the ```com.datecs.pinpad``` string needs to be added to the ```Supported external accessory protocols``` in the **.plist file**: + +````xml + UISupportedExternalAccessoryProtocols + + com.datecs.pinpad + +```` + +- **Background mode support**: Your application needs to support connection to external devices when in the background. For this reason, in the "Capabilities" section of the project settings, the **Background Modes** profile needs to be ON, and the ```External accessory communication ``` option must be checked. This is equivalent to adding the following entry in the .plist file: + + +````xml + UIBackgroundModes + + external-accessory + +```` + +- **C++ linker flag**: A part of the library is written in c++ therefore the **-lc++ linker flag** needs to be set. Add it under "Other Linker Flags" under the "Linking" section of your projects settings "Build Settings" tab. +- **Other settings**: To prevent the warning "file was built for archive which is not the architecture being linked (armv7s)", **set Build Active Architecture Only** to YES. + + +## Usage summary + +Any application using the Handpoint SDK should follow these steps: + +1. Define a class that implements the** HeftDiscoveryDelegate **protocol. +This class defines the behavior of the app when discovery related events are received from the SDK. +2. Define a class that implements the **HeftStatusReportDelegate** protocol (it can be the same as above). +This class defines the behavior of the app when connection and transaction related events are received from the SDK +3. Get a reference to the HeftManager singleton and assign your HeftDiscoveryDelegate instance as delegate. +4. If device is available through BT connection, start the discovery process by calling the** startDiscovery** function of the HeftManager and recover a list of the discovered devices by calling the **connectedCardReaders **function of the HeftManager. +5. If device is using a Lightning connector (HiPro devices), recover the device by directly calling the **connectedCardReaders** function of the HeftManager. +6. Connect to a device by calling the **clientForDevice** function of the HeftManager. +7. If connection is successful, the **didConnect** function of the HeftStatusReportDelegate instance will be invoked. +8. From this point, start processing transactions and have fun! + +## Usage details + +1. Define a class that implements the ** HeftDiscoveryDelegate **protocol. +This class will define the behavior of the application when discovery related events are received from the SDK. + +````objectivec + @interface MyDiscoveryDelegate () + @implementation MyDiscoveryDelegate +```` + +2. Define a class that implements the** HeftStatusReportDelegate **protocol (it can be the same as above). +This class will define the behavior of the application when connection and transaction related events are received from the SDK. + +````objectivec + @interface MyStatusReportDelegate () + @implementation MyStatusReportDelegate +```` + +3. Get a reference to the HeftManager singleton in SDK by calling the **sharedManager** class method. +Assign your HeftDiscoveryDelegate instance as delegate of the manager. + +````objectivec + MyDiscoveryDelegate* myDiscoveryDelegate = [[alloc MyDiscoveryDelegate] init]; + HeftManager* manager = [HeftManager sharedManager]; + manager.delegate = myDiscoveryDelegate; +```` + +4. If device is available through BT connection, start the discovery process by calling the **startDiscovery** function of the HeftManager. + +````objectivec + [manager startDiscovery]; +```` + +When a device is selected by the user in the “Select device” popup window, the **didFindAccessoryDevice** function of the HeftDiscoveryDelegate is invoked. + +````objectivec + - (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice + { + NSLog(@"Found new device"); + //Connect to found device or store it for later + } +```` + +When the discovery process is finished, the **didDiscoverFinished** function of the HeftDiscoveryDelegate instance will be invoked. Recover a list of all the discovered devices by calling the **connectedCardReaders** function of the HeftManager. + +````objectivec + - (void)didDiscoverFinished + { + NSMutableDictionary *discoveredDevices = [self.manager connectedCardReaders]; + } +```` + +5. If device is using a Lightning connection (HiPro devices), skip the previous step and recover the device by directly calling the **connectedCardReaders** function of the HeftManager. + +````objectivec +HeftRemoteDevice *lightningDevice = [[self.manager connectedCardReaders] firstObject]; +```` + +6. Connect to a device by calling the **clientForDevice** function of the HeftManager. + +* Expected parameters of this function are: + + - A discovered device (HeftRemoteDevice object). + + - A shared secret. The shared secret is a unique identifier. It is a used to link a merchant with his readers. Each one of your merchants will be assigned a different shared secret so it needs to be a configurable value in your application or backend. If you received a development kit with a card reader, our support team probably sent you a shared secret via email already. + + - A HeftStatusReportDelegate instance, which will be notified of all the events related with the device. + +```` objectivec + // Declare the shared secret (below SS is an example, please put the one sent by our support team) + NSString *sharedSecret =@"0102030405060708091011121314151617181920212223242526272829303132"; + // Connect to reader + [manager clientForDevice:device + sharedSecret:mySharedSecret + delegate:myStatusReportDelegate]; +```` + +7. If connection is successful, the **didConnect** function of the HeftStatusReportDelegate instance will be invoked. Function receives as parameter a HeftClient object, whose reference must be stored since it is the communication bridge to the device we have connected to. + +```` objectivec + - (void)didConnect:(id )client + { + self.heftClient = client; + } +```` + +8. Once connected to the card reader, transactions can be started through the HeftClient object. For example, the next code starts a sale of 100 GBP: + +````objectivec +[self.heftClient saleWithAmount:100 currency:@"GBP" cardholder:YES]; +```` + +9. When a transaction has been initiated (f.ex saleWithAmount), the HeftClient alerts the HeftStatusReportDelegate object by invoking **responseStatus** during the process and **responceFinanceStatus** when the process has finished. + +````objectivec + - (void)responseStatus:(id)info + { + NSLog(@"responseStatus:"); + NSLog(info.status); + NSLog(info.xml.description); + } + + - (void)responseFinanceStatus:(id)info + { + NSLog(@"responseFinanceStatus:"); + NSLog(info.status); + NSLog(info.customerReceipt); + NSLog(info.xml.description); + } +```` + +10. In case you are using the **SDK simulator**, the behavior changes according to the amount of the transaction: + +| **Amount** | **Behavior** | +| ----------- | ----------- | +| 1000 | Declined transaction| +| 2000 | User Cancelled| +| 3000 | Signature Requested| +| Other amount | Approved transaction| \ No newline at end of file diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosintroduction.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosintroduction.md new file mode 100644 index 0000000..64b6b1f --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosintroduction.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 1 +id: iosintroduction +--- + + +# Introduction + + +
+
+
+

iOS SDK

+
+
+ + + +
+
+ Get the latest iOS SDK! +
+
+
+ +

+ +:::tip +If you are currently using 3.x of the iOS SDK, take a look at the [migration guide](iosmigration.md) to 4.x +::: + + +The Handpoint iOS SDK provides a simple application programming interface for the Handpoint payment terminals. + +:::info +Please note that before submitting an app to the Apple App store a MFi hardware request has to be submitted to Apple, +to be able to use an external accessory. Please fill our [this form](http://hndpt.co/hp-mfi) before submitting your app to the App store and we will get back to you. +If you have any questions, contact us for more details. +::: diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosmigration.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosmigration.md new file mode 100644 index 0000000..d99260b --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosmigration.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 3 +id: iosmigration +--- + + + + +# Migration from 3.X + + +:::tip +Version 4.0.0 introduces a well defined, typed, way of passing extra values, options, parameters or flags to the financial transactions. +::: + + +We have unified all the extra and optional parameters in an Options object. Different operations have different options. + +**1. For a [Sale](iostransactions.md#2) or [Sale and Tokenize](iostransactions.md#4) operation**
If you use a customer reference: + +``` + SaleOptions *options = [SaleOptions new]; + options.customerReference = @"Your customer reference"; +``` + + +If you need Multi MID / Custom merchant Authentication: + + +````objectivec + MerchantAuth *auth = [MerchantAuth new]; + Credential *cred = [Credential new]; + //Optionally + cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; + //Optionally + cred.mid = @"mid"; + //Optionally + cred.tid = @"tid"; + //Add as many credentials as Acquirers your merchant have agreements with + [auth add:cred]; + options.merchantAuth = auth; +```` + +If you want to specify the budget period Only available for `SureSwipe/Altech` (South Africa): + +````objectivec +options.divideByMonths = @"YOUR_BUDGET_NUMBER"; + ```` + +Finally: + +````objectivec +[self.api saleWithAmount:amount currency:currency options:options]; +```` + + +**2. for a [Refund](iostransactions.md#5) operation (less optional parameters)**
If you use a customer reference: + +````objectivec + SaleOptions *options = [SaleOptions new]; + options.customerReference = @"Your customer reference"; +```` + +If you need Multi MID / Custom merchant Authentication: + +````objectivec +MerchantAuth *auth = [MerchantAuth new]; + Credential *cred = [Credential new]; + //Optionally + cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; + //Optionally + cred.mid = @"mid"; + //Optionally + cred.tid = @"tid"; + //Add as many credentials as Acquirers your merchant have agreements with + [auth add:cred]; + options.merchantAuth = auth; +```` +Finally: + +```objectivec +[self.api refundWithAmount:amount currency:currency transaction:originalTransactionID options:options]; +``` + +**3. For the rest of operations**
If you use a customer reference: + +```objectivec +options.customerReference = @"Your customer reference"; +``` \ No newline at end of file diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosobjects.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosobjects.md new file mode 100644 index 0000000..225b5c7 --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosobjects.md @@ -0,0 +1,717 @@ +--- +sidebar_position: 11 +id: iosobjects +--- + + +# Objects + +## HeftManager{#19} + +`HeftManager` Object + +The HeftManager is used for discovering and connecting to devices as well as creating a HeftClient object for the appropriate payment terminal. The manager reports messages to the HeftDiscoveryDelegate protocol during the discovery process. Starting the manager is the first thing to be done after loading up an UIView which enables the user to search for and connect to bluetooth terminals. When starting the manager an object (usually the UIViewController itself) is passed as the HeftDiscoveryDelegate delegate to report to. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `devicesCopy`
*NSArray* | **DEPRECATED_ATTRIBUTE**: Array which contains the discovered payment terminals.| +| `connectedCardReaders`
*NSArray* | Array which contains the discovered payment terminals.| +| `delegate`
*NSObject*| Key for value in mpedInfo.| +| `version`
*NSString* | Current HeftManager version.| + +**Code example** + +````objectivec +// Create a manager on view load +- (void)viewDidLoad{ + [super viewDidLoad]; + HeftManager* manager = [HeftManager sharedManager]; + manager.delegate = self; + [manager resetDevices]; // Clean out the payment terminal list +} +```` + +**Methods** + +[**Start Discovery**](iosdevicemanagement.md#32) + +- (void)startDiscovery; +*** + +[**Shared Manager**](iosdevicemanagement.md#11) + ++ (HeftManager `*`)sharedManager; +*** + +[**Client for device (NSString)**](iosdevicemanagement.md#12) + +- (void)clientForDevice:(HeftRemoteDevice `*`)device sharedSecret:(NSString `*`)sharedSecret delegate:(NSObject HeftStatusReportDelegate `*`)delegate; + +## HeftClient{#22} + +`HeftClient` Object + +High level interface for the API. HeftClient handles the communication between your application and the payment terminal. The HeftClient object also stores information about the payment terminal in the mpedInfo dictionary. To create a new HeftClient object the clientForDevice method is called from an instance of the HeftManager. Transaction requests (and the acceptSignature response) are done by calling HeftClient methods with the relevant input. The library reports the status of the requests by calling delegates of the HeftStatusReportDelegate protocol. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `sharedSecret`
*NSString* | The shared secret is a unique authentication key provided by Handpoint for each merchant.| +| `mpedInfo`
*NSDictionary* | Dictionary with payment terminal details, obtained from the device on interface creation.| +| `isTransactionResultPending`
*BOOL* | Indicates whether a transaction result is pending on the payment terminal.

**Note: A pending transaction result is retained by the payment terminal if a disconnect occurs between the terminal and your application before the transaction result can be delivered during a SALE, REFUND or VOID operation.**| +| `kSerialNumberInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kPublicKeyVersionInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kEMVParamVersionInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kGeneralParamInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kManufacturerCodeInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kModelCodeInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kAppNameInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kAppVersionInfoKey`
*NSString Constant* | Key for value in mpedInfo| +| `kXMLDetailsInfoKey`
*NSString Constant* | Key for value in mpedInfo| + + +**Code example** + +````objectivec +//clientForDevice:sharedSecret:delegate: +//Creates a HeftClient object(connection to device) +-(void)connectToFirstCardReaderWith:(NSData*)sharedSecret; +{ + //Try to connect to the first device in the devices array + [heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecret:sharedSecret delegate:self]; + //Client calls the didConnect delegate function if successful +} + +//.... + +//didConnect: +//Called when a connection to a specified device was created. +-(void)didConnect:(id)client +{ + // connected successfully to a device + // assigned the client to the heftClient property + heftClient = client; +} + +// ..... + +// Do one sale later in code +[heftClient saleWithAmount:1000 currency:@"GBP" cardholder:YES]; +```` + +**Methods** + +[**cancel**] + +- (void)cancel; +*** + +[**saleWithAmount**](iostransactions.md#2) + +- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present; +*** + +[**saleWithAmount**](iostransactions.md#2) + +- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference; +*** + +[**saleWithAmount**](iostransactions.md#2) + +- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference divideBy:(NSString*)months; +*** + +[**refundWithAmount**](iostransactions.md#5) + +- (BOOL)refundWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present; +*** + +[**refundWithAmount**](iostransactions.md#5) + +- (BOOL)refundWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present reference:(NSString*)reference; +*** + +[**saleVoidWithAmount**](iostransactions.md#3) + +- (BOOL)saleVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction; +*** + +[**refundVoidWithAmount**](iostransactions.md#6) + +- (BOOL)refundVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction; +*** + +[**retrievePendingTransaction**](iostransactions.md#8) + +- (BOOL)retrievePendingTransaction; +*** + +[**enableScanner**](iosdevicemanagement.md#36) + +- (BOOL)enableScanner; +*** + +**enableScannerWithMultiScan** + +- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan; +*** + +**enableScannerWithMultiScan** + +- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan buttonMode:(BOOL)buttonMode; +*** + +**enableScannerWithMultiScan** + +- (BOOL)enableScannerWithMultiScan:(BOOL)multiScan buttonMode:(BOOL)buttonMode timeoutSeconds:(NSInteger)timeoutSeconds; +*** + +[**Disable scanner**](iosdevicemanagement.md#disable-scanner) + +- (BOOL)disableScanner; +*** + +**financeStartOfDay** + +- (BOOL)financeStartOfDay; +*** + +**financeEndOfDay** + +- (BOOL)financeEndOfDay; +*** + +[**financeInit**](iosdevicemanagement.md#47) + +- (BOOL)financeInit; +*** + +[**acceptSignature**](iostransactions.md#7) + +- (void)acceptSignature:(BOOL)flag; +*** + +**getEMVConfiguration** + +- (BOOL)getEMVConfiguration; +*** + +## HeftRemoteDevice{#23} + +`HeftRemoteDevice` Object + +An object containing a reference to the accessory device which is passed to the HeftClient on creation. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `name`
*NSString* | Name of device| +| `accessory`
*EAAccessory* | The EAAccessory object| +| `address`
*NSString* | Address of device| + + +## HeftDiscoveryDelegate + +`HeftDiscoveryDelegate` + +Notifications sent by the SDK on various events - new available device found, connection lost, connection found, etc + +**Methods** + +[**didDiscoverFinished**](iosevents.md#37) + +- (void)didDiscoverFinished; +*** + +[**didFindAccessoryDevice**](iosevents.md#38) + +- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice; +*** + +[**didLostAccessoryDevice**](iosevents.md#39) + +- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice; +*** + +## HeftStatusReportDelegate + +`HeftStatusReportDelegate` Object + +Notifications sent by the SDK on various events - connected to device, request signature, response on error etc. + +**Methods** + +[**didConnect**](iosevents.md#20) + +- (void)didConnect:(id-HeftClient)client; +*** + +[**responseStatus**](iosevents.md#14) + +- (void)responseStatus:(id-ResponseInfo)info; +*** + +[**responseError**](iosevents.md#15) + +- (void)responseError:(id-ResponseInfo)info; +*** + +[**responseFinanceStatus**](iosevents.md#16) + +- (void)responseFinanceStatus:(id-FinanceResponseInfo)info; +*** + +[**requestSignature**](iosevents.md#17) + +- (void)requestSignature:(NSString*)receipt; +*** + +[**cancelSignature**](iosevents.md#40) + +- (void)cancelSignature; +*** + +[**responseRecoveredTransactionStatus**](iosevents.md#44) + +- (void)responseRecoveredTransactionStatus:(id-FinanceResponseInfo)info; +*** + +[**responseScannerEvent**](iosevents.md#41) + +- (void)responseScannerEvent:(id-ScannerEventResponseInfo)info; +*** + +[**responseScannerDisabled **](iosevents.md#42) + +- (void)responseScannerDisabled:(id-ScannerDisabledResponseInfo)info; +*** + +**responseEMVReport** + +- (void)responseEMVReport:(NSString *)report; +*** + + +## ResponseInfo{#24} + +`ResponseInfo` Object + +A ResponseInfo object is passed to the ResponseStatus delegate. It contains information from the payment terminal about the status of the current transaction. There are two properties: status and xml. status is a string and xml is a dictionary. Usually status contains a descriptive enough message to know what is going, this messsage should be displayed to the yser. The xml dictionary has detailed information on the current state of the payment terminal. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `statusCode`
*int* | A numerical representation of the status.| +| `status`
[*Status as NSString*](#45) | Status message of the financial operation.| +| `xml`
[*XML as NSDictionary*](#46) | Details of the transaction.| + + +## FinanceResponseInfo{#25} + +`FinanceResponseInfo` Object + +A FinanceResponseInfo is passed to the responseFinanceStatus delegate at the end of a transaction. It contains all necessary information about the outcome of the transaction. FinanceResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to the authorisedAmount, transactionId and the html formatted receipts. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `financialResult`
*NSInteger* | A numerical representation of a financial status result.
EFT_FINANC_STATUS_UNDEFINED 0x00
EFT_FINANC_STATUS_TRANS_APPROVED 0x01
EFT_FINANC_STATUS_TRANS_DECLINED 0x02
EFT_FINANC_STATUS_TRANS_PROCESSED 0x03
EFT_FINANC_STATUS_TRANS_NOT_PROCESSED 0x04
EFT_FINANC_STATUS_TRANS_CANCELLED 0x05| +| `isRestarting`
*BOOL* | Indicates whether the card reader is about to restart or not (usually triggered after a software update is received).If a restart is imminent then you should disconnect from the card reader and wait for it to be visible again.| +| `authorisedAmount`
*NSInteger* | Amount in the smallest unit of the currency - For example 1000 in case the CurrencyCode is "0826" (GBP) corresponds to 10.00 pounds.| +| `transactionId`
*NSString* | The id of the current transaction.| +| `customerReceipt`
*NSString* | Customer receipt in html format.| +| `merchantReceipt`
*NSString* | Merchant receipt in html format.| +| `statusMessage`
*NSString* | A human readable message describing the result of the transaction.| +| `type`
*NSString* | Type of financial operation ("SALE" is an example).| +| `finStatus`
*NSString* | The financial status describes the outcome of the transaction("AUTHORISED" is an example).| +| `requestedAmount`
*NSString* | Amount sent in the original request to the payment terminal.| +| `gratuityAmount`
*NSString* | The gratuity amount is an additional amount (for example a tip) added to the requested amount. This field is returned when the tipping functionality is activated on the payment terminal.

Example: a sale is started for 10.00 and the payment terminal is set to support tipping. The terminal asks the cardholder if a tip should be added for the transaction. The cardholder inputs an additional amount as a tip, lets say 1.00. The card is then charged for the requested amount, 10.00, as well as the additional gratuity amount, 1.00. The resulting charge will be for a total of 11.00.| +| `gratuityPercentage`
*NSString* | The gratuity percentage is used to calculate an additional amount (for example a tip) added to the requested amount. The terminal calculates the gratuity amount based on the percentage chosen by the cardholder on the payment terminal, the amount is rounded up to the closest whole number.

Example: a sale is started for 10.00 and the payment terminal is set to support tipping. The terminal asks the cardholder if a tip should be added for the transaction. The cardholder chooses a % as a tip, lets say 10%. The card is then charged for the requested amount, 10.00, as well as the additional gratuity amount, 1.00 (10%). The resulting charge will be for a total of 11.00.| +| `totalAmount`
*NSString* | The total amount is the amount for which the card was charged in the minor unit of the currency. It is possible for the total amount to be different from the requested amount if a tip is added or the transaction is partially approved (US acquirers only).| +| `currency`
*NSString* | The currency used for the transaction.| +| `eFTTransactionID`
*NSString* | The EFT (electronic funds transfer) transaction id is a unique GUID assigned to the transaction. This id is used as a parameter for the sale or refund reversal function in case the transaction needs to be reversed.| +| `originalEFTTransactionID`
*NSString* | This field is only returned in a reversal or refund transaction and references the GUID of the original transaction being refunded or reversed.| +| `eFTTimestamp`
*NSString* | The eFTTimestamp is the time at which the transaction was processed.| +| `authorisationCode`
*NSString* | This is the approval code returned by the payment processor when a transaction is approved.| +| `verificationMethod`
*NSString* | Cardholder verification method, for example "PIN".| +| `cardEntryType`
*NSString* | Method used by the terminal to read the card.| +| `cardSchemeName`
*NSString* | A string representing different card brands (VISA, Mastercard, etc...)| +| `errorMessage`
*NSString* | Detailed reason for the transaction error.| +| `customerReference`
*NSString* | If a customer reference was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The customer reference can be used at your will for tracking of transactions.| +| `budgetNumber`
*NSString* | If a budget number was added, as an optional parameter, when the transaction was started. It is received here, unaltered. The budget number can be used to split payments over a period of months.| +| `recoveredTransaction`
*BOOL* | This flag is true if the transaction result retrieved is from a previous transaction which failed to get sent from the payment terminal to your application, false otherwise. In case the communication between your application and the terminal breaks down, the terminal will attempt to send the result of the previous transaction as an immediate reply when the next transaction is started. If this happens, the transaction is flagged as a "RecoveredTransaction".| +| `cardTypeId`
*NSString* | DEPRECATED - The card type id is an identifier inside the Handpoint gateway which represents what kind of card was used. "U015" for an example represents SAS Airline-Systems in our systems.| +| `chipTransactionReport`
*NSString* | If present, a full report of the card EMV parameters.| +| `deviceStatus`
*NSString* | Gets the device status.| +| `dueAmount`
*NSString* | If there's still a part of the amount to be paid, in case of a partial approval (US acquirers only).| +| `balance`
*NSString* | The balance of the cardholder's card, if the bank/acquirer supports it.| +| `CardToken`
*NSString* | Token representing the PAN of the card.| + + +## ScannerEventResponseInfo{#26} + +`ScannerEventResponseInfo` Object + +A ScannerEventResponseInfo is passed to the responseScannerEvent delegate when a scan is detected. ScannerEventResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to the scanCode string. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `statusCode`
*int* | A numerical representation of the status.| +| `status`
[*Status as NSString*](#45) | Financial transaction status message.| +| `xml`
[*XML as NSDictionary*](#46) | Feedback with xml details about transaction from the card reader.| +| `scanCode`
*NSString* | The code that was scanned.| + +## ScannerDisabledResponseInfo{#27} + +`ScannerDisabledResponseInfo` Object + +This object contains information about the scanner operation. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `statusCode`
*int* | A numerical representation of the status.| +| `status`
[*Status as NSString*](#45) | Financial transaction status.| +| `xml`
[*XML as NSDictionary*](#46) | XML details from the payment terminal.| + + +## Transaction Details{#46} + +`XML as NSDictionary` Object + +The contents of the xml property depend on which type of operation the payment terminal is responding to. Listed below are all possible keys in the dictionary. Note that not all fields are included all the time. + +**StatusMessage** + +The status of the transaction, for example "Waiting for pin". +*** + +**TransactionType** + +The type of transaction performed: UNDEFINED SALE VOID_SALE REFUND VOID_REFUND REVERSAL, TOKENIZE_CARD SALE_AND_TOKENIZE_CARD +*** + +**FinancialStatus** + +The result of the transaction: UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED PARTIAL_APPROVA +*** + +Description of the different financial statuses: + +| Parameter | Notes | +| ----------- | ----------- | +| `UNDEFINED`
| Any Financial Status other than the below mentioned financial statuses will be `UNDEFINED`. UNDEFINED means that the SDK couldn't get a response from the Gateway. An automatic cancellation service will try to cancel the transaction in case it was approved. | +| `AUTHORISED`
| The transaction (Sale, Refund,...) has been authorised. Consider this value as "successful". | +| `DECLINED`
| The transaction has been declined by the acquirer or issuer. | +| `PROCESSED`
| The `update` operation was successful.| +| `FAILED`
| Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to `FAILED`. | +| `CANCELLED`
| The transaction has been cancelled. For example if the `stopCurrentTransaction` operation has been used or the cancel button on the terminal has been pressed. | +| `PARTIAL_APPROVAL`
| A partial approval is the ability to partially authorize a transaction if the cardholder does not have the funds to cover the entire cost on their card. The merchant can obtain the remainder of the purchase amount in another form of payment. `PARTIAL_APPROVAL` is **only** applicable to the United States market. | + + +**RequestedAmount** + +The requested amount is the transaction amount sent to the terminal. +*** + +**GratuityAmount** + +The gratuity amount entered by the cardholder, if any. +*** + +**GratuityPercentage** + +The gratuity amount, as a percentage of the requested amount. +*** + +**TotalAmount** + +The total of the gratuity and requested amount. +*** + +**TransactionID** + +The transaction number used for this transaction, as maintained by the Eft Client. +*** + +**EFTTransactionID** + +The EFT reference, given by the system, to make the transaction unique. +*** + +**OriginalEFTTransactionID** + +The original EFT reference, given by the POS, as part of a VOID_SALE or a VOID_REFUND transaction. +*** + +**EFTTimestamp** + +The date and time of the transaction, in ISO format (YYYYMMDDHHmmSS). +*** + +**AuthorisationCode** + +The transaction authorization code, as given by the system. +*** + +**CVM** + +The Cardholder Verfication Method: UNDEFINED, SIGNATURE, PIN, PIN_SIGNATURE, FAILED, NOT_REQUIRED +*** + +**CardEntryType** + +The card data acquisition type: UNDEFINED, MSR, ICC, CNP +*** + +**CardSchemeName** + +The card brand : MasterCard, Visa, Maestro, American Express, Discover, JCB, Diners, UnionPay +*** + +**CardTypeId** + +DEPRECATED - The ID of the Card Type. +*** + +**SerialNumber** + +The serial number of the payment terminal. +*** + +**BatteryStatus** + +A number, followed by the % sign, which indicates the current charge level of the battery. +*** + +**BatterymV** + +An integer, which represent the battery charge, in mV. +*** + +**BatteryCharging** + +Indicates whether the battery is charging, or not. Values are true or false. +*** + +**ExternalPower** + +Indicates whether the PED is connected to an external power source (e.g. a AC adapter). Values are true or false. +*** + +**ApplicationName** + +The name of the application running on the payment terminal. +*** + +**ApplicationVersion** + +A version string of the form major.minor.build”(e.g. 1.2.118). +*** + +**ErrorMessage** + +Description of the error, if any. +*** + +**RecoveredTransaction** + +Indicates that the transaction result is a recovered transaction. The key is only included if value is true. +*** + +## CmdIds + +`card reader Status messages` Value List + +Status messages received from the payment terminal: + +**Possible values** + +`EFT_PP_STATUS_SUCCESS`
+`EFT_PP_STATUS_INVALID_DATA`
+`EFT_PP_STATUS_PROCESSING_ERROR`
+`EFT_PP_STATUS_COMMAND_NOT_ALLOWED`
+`EFT_PP_STATUS_NOT_INITIALISED`
+`EFT_PP_STATUS_CONNECT_TIMEOUT`
+`EFT_PP_STATUS_CONNECT_ERROR`
+`EFT_PP_STATUS_SENDING_ERROR`
+`EFT_PP_STATUS_RECEIVING_ERROR`
+`EFT_PP_STATUS_NO_DATA_AVAILABLE`
+`EFT_PP_STATUS_TRANS_NOT_ALLOWED`
+`EFT_PP_STATUS_UNSUPPORTED_CURRENCY`
+`EFT_PP_STATUS_NO_HOST_AVAILABLE`
+`EFT_PP_STATUS_CARD_READER_ERROR`
+`EFT_PP_STATUS_CARD_READING_FAILED`
+`EFT_PP_STATUS_INVALID_CARD`
+`EFT_PP_STATUS_INPUT_TIMEOUT`
+`EFT_PP_STATUS_USER_CANCELLED`
+`EFT_PP_STATUS_INVALID_SIGNATURE`
+`EFT_PP_STATUS_WAITING_CARD`
+`EFT_PP_STATUS_CARD_INSERTED`
+`EFT_PP_STATUS_APPLICATION_SELECTION`
+`EFT_PP_STATUS_APPLICATION_CONFIRMATION`
+`EFT_PP_STATUS_AMOUNT_VALIDATION`
+`EFT_PP_STATUS_PIN_INPUT`
+`EFT_PP_STATUS_MANUAL_CARD_INPUT`
+`EFT_PP_STATUS_WAITING_CARD_REMOVAL`
+`EFT_PP_STATUS_TIP_INPUT`
+`EFT_PP_STATUS_SHARED_SECRET_INVALID`
+`EFT_PP_STATUS_SHARED_SECRET_AUTH`
+`EFT_PP_STATUS_WAITING_SIGNATURE`
+`EFT_PP_STATUS_CONNECTING`
+`EFT_PP_STATUS_SENDING`
+`EFT_PP_STATUS_RECEIVEING`
+`EFT_PP_STATUS_DISCONNECTING`
+`EFT_PP_STATUS_PIN_INPUT_COMPLETED`
+`EFT_PP_STATUS_POS_CANCELLED`
+`EFT_PP_STATUS_REQUEST_INVALID`
+`EFT_PP_STATUS_CARD_CANCELLED`
+`EFT_PP_STATUS_CARD_BLOCKED`
+`EFT_PP_STATUS_REQUEST_AUTH_TIMEOUT`
+`EFT_PP_STATUS_REQUEST_PAYMENT_TIMEOUT`
+`EFT_PP_STATUS_RESPONSE_AUTH_TIMEOUT`
+`EFT_PP_STATUS_RESPONSE_PAYMENT_TIMEOUT`
+`EFT_PP_STATUS_ICC_CARD_SWIPED`
+`EFT_PP_STATUS_REMOVE_CARD`
+`EFT_PP_STATUS_SCANNER_IS_NOT_SUPPORTED`
+`EFT_PP_STATUS_SCANNER_EVENT`
+`EFT_PP_STATUS_BATTERY_TOO_LOW`
+`EFT_PP_STATUS_ACCOUNT_TYPE_SELECTION`
+`EFT_PP_STATUS_BT_IS_NOT_SUPPORTED`
+`EFT_PP_STATUS_PAYMENT_CODE_SELECTION`
+`EFT_PP_STATUS_PARTIAL_APPROVAL`
+`EFT_PP_STATUS_AMOUNT_DUE_VALIDATION`
+`EFT_PP_STATUS_INVALID_URL`
+`EFT_PP_STATUS_WAITING_CUSTOMER_RECEIPT`
+`EFT_PP_STATUS_PRINTING_MERCHANT_RECEIPT`
+`EFT_PP_STATUS_PRINTING_CUSTOMER_RECEIPT`
+`EFT_PP_STATUS_WAITING_HOST_MSG_TO_HOST`
+`EFT_PP_STATUS_WAITING_HOST_MSG_RESP`
+`EFT_PP_STATUS_INITIALISATION_COMPLETE`
+ + +## Status strings{#45} + +`Status as NSString` Value List + +An NSString containing the status message - can be one of the following: + +**Possible values** + +`Success`
+`Invalid data`
+`Processing error`
+`Not allowed`
+`Not initialized`
+`Connect timeout`
+`Connect error`
+`Sending error`
+`Receiveing error`
+`No data available`
+`Transaction not allowed`
+`Unsupported currency`
+`No host available`
+`Card reader error`
+`Card reading failed`
+`Invalid card`
+`Input timeout`
+`User cancelled`
+`Invalid signature`
+`Waiting card`
+`Card inserted`
+`Application selection`
+`Application confirmation`
+`Amount validation`
+`PIN input`
+`Manual card input`
+`Waiting card removal`
+`Tip input`
+`Shared secret invalid`
+`Connecting`
+`Sending`
+`Receiving`
+`Disconnecting`
+`PIN entry completed`
+`Merchant cancelled the transaction`
+`Request invalid`
+`Card cancelled the transaction`
+`Blocked card`
+`Request for authorisation timed out`
+`Request for payment timed out`
+`Response to authorisation request timed out`
+`Response to payment request timed out`
+`Please insert card in chip reader`
+`Remove the card from the reader`
+`This device does not have a scanner`
+`Scanner is not supported`
+`Scanner event`
+ +## Process details + +The following table contains result codes that can occur in the COMMAND response STATUS field (see section 1.3 above). + +In addition the following table contains the text information presented in the StatusMessage field that is part of the FinancialTransactionResponse Xml response object. + +All values are in hex in the following table. + +| Status ID | Value | StatusMessage| Details | +| ----------- | ----------- |----------- | ----------- | +| EFT_SUCCESS | 0001| One of the following: "" (an empty string) "AUTH CODE #" "REFUND ACCEPTED" "REVERSAL ACCEPTED"|Operation completed successfully. No further actions required.| +| EFT_INVALID_DATA | 0002|"Invalid data"|Invalid COMMAND request object, from the POS App, at the start of an operation. Please retry the operation. If the issue persists please contact technical support and provide any logs gathered from the POS for the request being sent.| +|EFT_PROCESSING_ERROR |0003| "Processing error"| An unexpected error occurred during processing. Please retry the operation. If the issue persists please contact technical support and provide transaction information such as transaction id, timestamp and device serial number.| +|EFT_COMMAND_NOT_ALLOWED| 0004| "Command not allowed"| The card reader is currently busy processing another command. Please retry the operation once the current operation has completed.|| +|EFT_NOT_INITIALISED |0005 |"Device is not initialized"| The current operation can’t be completed because there is a pending software update that must be applied before processing can continue. Please retry the operation after the card reader has restarted itself.| +|EFT_CONNECT_TIMEOUT |0006 |"Connection time out detected"| The back end connection timed out during an update. Please retry the operation. If the issue persists please contact technical support.| +|EFT_CONNECT_ERROR |0007 |"Connection error" |It was not possible to establish a connection to the back end system during an update operation. Please retry the operation. If the issue persists please contact technical support.| +|EFT_SENDING_ERROR |0008 |"Send error" |A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Once verified please retry the operation.| +|EFT_RECEIVING_ERROR |0009| "Receiving error"| A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Once verified please retry the operation.| +|EFT_TRANS_NOT_ALLOWED |000B| "Transaction not allowed"| `Currently not used`| +|EFT_UNSUPPORTED_CURRENCY| 000C| "Currency not supported"| A currency has been selected that the card reader has not been configured for. Please select the correct currency and retry the operation. Alternatively, please contact technical support and ask for the specific currency to be supported.| +|EFT_NO_HOST_AVAILABLE| 000D |"No host configuration found"| An update was initiated but the card reader could not find any host information for the back end system, even though it otherwise contains valid configuration. This is indicative of an invalid `hostBlock` block with in the `HostList` block in this device configuration, which was placed on the card reader during a previous update. Please contact technical support and ask for a replacement device. The card reader will be unable to update itself and must be replaced.| +|EFT_CARD_READER_ERROR |000E |"Card reader error"| Error detected in the chip reader or the magnetic stripe reader. Please retry the operation. If the issue persists please contact technical support and ask for a replacement reader.| +|EFT_CARD_READING_FAILED| 000F| "Failed to read card data"| The card reader could not read any data from the card. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.| +|EFT_INVALID_CARD |0010 |"INVALID CARD" |The card reader detected invalid card data. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.| +|EFT_INPUT_TIMEOUT |0011| "Timeout waiting for user input"| The card reader timed out while waiting for a user action. No further actions required.| +|EFT_USER_CANCELLED |0012| "TRANSACTION VOID" "User cancelled the transaction" |The current operation was cancelled by card holder. No further actions required.| +|EFT_SHARED_SECRET_INVALID| 001D| "Shared Secret invalid"| The card reader believes that the POS App has an incorrect shared secret. No financial operations will be possible (e.g. SALE, REFUND). Please type the correct shared secret into the POS App or contact technical support for further assistance.| +|EFT_SHARED_SECRET_AUTH |001E |"Authenticating POS"| The card reader is about to challenge the POS App for a correct shared secret. No further actions are required.| + | REPORT STATUS SPECIFIC| +|EFT_INVALID_SIGNATURE |0013| "TRANSACTION VOID"| The merchant indicated that the signature provided by the card holder was invalid. No further actions are required.| +|EFT_WAITING_CARD |0014| "Waiting for card" |The card reader is waiting for a card to be inserted into the chip reader or for a card to be swiped (only applies to card readers with external MSR). Insert or swipe a card to continue with the transaction.| +|EFT_CARD_INSERTED |0015| "Card detected" |`Currently not used`| +|EFT_APPLICATION_SELECTION |0016| "Waiting for application selection" |The card reader is waiting for the card holder to select a card application to be used for the transaction. The card holder must select an application for use (e.g. VISA, MASTERCARD, etc.) and should then press either the OK button to continue. Press the C/Cancel button to abort the transaction.| +|EFT_APPLICATION_CONFIRMATION| 0017| "Waiting for application confirmation"| The card reader is waiting for the card holder to confirm that the displayed card application should be used for the transaction. The card holder should press either the OK or the C/Cancel button.| +|EFT_AMOUNT_VALIDATION| 0018 |"Waiting for amount validation"| The card reader is waiting for the card holder to confirm that the amount presented is correct. The card holder should press either the OK or the C/Cancel button.| +|EFT_PIN_INPUT |0019| "Waiting for PIN entry"| The card reader is waiting for the card holder to enter his/her PIN. The card holder should enter his PIN and then press the OK button to continue. For PIN bypass press the OK button without entering any PIN digits (this will trigger signature fallback). Press the C/Cancel button to abort the transaction. Note: It is not possible to cancel this operation from the POS App.| +|EFT_MANUAL_CARD_INPUT |001A| "Waiting for manual card data"| `Currently not used`| +|EFT_WAITING_CARD_REMOVAL| 001B| "Waiting for card removal"| A card was detected in the card reader at the start of a transaction, presumably left there from a previous transaction. Please remove the card and restart the operation.| +|EFT_TIP_INPUT |001C| "Waiting for gratuity" |The card reader is waiting for the card holder to enter/confirm tip/gratuity information.| +|EFT_WAITING_SIGNATURE |001F| "Waiting for signature" |The card reader is waiting for confirmation from the merchant that the card holder signature is valid. The merchant should press either the Accepted or Declined/Cancel in the POS App. Pressing Cancel or OK on the card reader will not have any effect.| +|EFT_WAITING_HOST_CONNECT |0020| "Connecting to host"| The card reader is establishing a connection to the back end system. No further actions are required.| +|EFT_WAITING_HOST_SEND| 0021 |"Sending data to host" |The card reader is sending data to the back end system. No further actions are required.| +|EFT_WAITING_HOST_RECEIVE| 0022| "Waiting for data from host" |The card reader is waiting for data from to the back end system. No further actions are required.| +|EFT_WAITING_HOST_DISCONNECT| 0023| "Disconnecting from host"| The card reader is disconnecting from the back end system. No further actions are required.| +|EFT_PIN_INPUT_COMPLETED| 0024| "PIN entry completed"| PIN entry has been completed. No further actions required.| +|EFT_POS_CANCELLED |0025| "TRANSACTION VOID" |The current operation was cancelled by merchant. No further actions required.| +|EFT_REQUEST_INVALID| 0026| "Request invalid"| Card not allowed with this transaction type.| +|EFT_CARD_CANCELLED |0027| "TRANSACTION VOID"| The chip on the card cancelled the transaction. No further actions required.| +|EFT_CARD_BLOCKED |0028| |"CARD BLOCKED" |The card used in the transaction is blocked. Please retry the transaction with a non-blocked card.| +|EFT_REQUEST_AUTH_TIMEOUT |0029| "Request for authorisation timed out"| Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support.| +|EFT_REQUEST_PAYMENT_TIMEOUT| 002A| "Request for payment timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support.| +|EFT_RESPONSE_AUTH_TIMEOUT |002B| "Response to authorisation request timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support.| +|EFT_RESPONSE_PAYMENT_TIMEOUT| 002C| "Response to payment request timed out" |Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. You MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Once you have verified that the transaction did not go through then please make sure the phone/pc has an internet connection and then retry the operation.| +|EFT_ICC_CARD_SWIPED| 002D| "Please insert card in chip reader" |`Currently not used`| +|EFT_REMOVE_CARD |002E| "Remove the card from the reader" |`Currently not used`| +|EFT_SCANNER_IS_NOT_SUPPORTED| 002F| "This device does not have a scanner" |Bar-code scanner hardware is not present on this card reader. No further actions are required.| +|EFT_SCANNER_EVENT| 0030| "" |Bar-code data was just read with the bar-code scanner and returned to the POS App. No further actions are required.| +|EFT_BATTERY_TOO_LOW| 0031| "Operation cancelled, the battery is too low. Please charge."| An operation was started, but the battery charge level is too low to complete the operation. Please recharge the card reader.| +|EFT_ACCOUNT_TYPE_SELECTION| 0032| "Waiting for account type selection"| The card reader is waiting for the card holder to choose an account type for the transaction (i.e. default, credit, cheque/debit or savings).| \ No newline at end of file diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iosprocessing.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosprocessing.md new file mode 100644 index 0000000..ea2885b --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosprocessing.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 4 +id: iosprocessing +--- + + +# 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 server: + +**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/ios_versioned_docs/version-iOS SDK 4.0.2/iosreleasenotes.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iosreleasenotes.md new file mode 100644 index 0000000..8a07f74 --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iosreleasenotes.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +id: iosreleasenotes +--- + + + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 4.0.2 +**Fixes**: +- Crash due to vector index out of bounds. + +## 4.0.1 +**Fixes**: + - Multi MID fix for INTERAC and POSTBRIDGE acquirers. + +## 4.0.0 +**Features**: + - Support for Multi MID and HiPro scanner fixes. + diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iossdkprocessing.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iossdkprocessing.md new file mode 100644 index 0000000..b614ac1 --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iossdkprocessing.md @@ -0,0 +1,373 @@ +--- +sidebar_position: 7 +id: iossdkprocessing +--- + + +# Integration Example + +## HandpointModule header + +**HandpointModule.h** + +````objectivec +#import "HandpointAll.h" + +@interface HandpointModule : NSObject + +- (instancetype)initWithSharedSecret:(NSString *)sharedSecret; + +- (void)saleWithAmount:(NSInteger)amount + currency:(NSString *)currency; + +- (void)refundWithAmount:(NSInteger)amount + currency:(NSString *)currency; + +- (void)saleReversalWithAmount:(NSInteger)amount + currency:(NSString *)currency + originalTransactionID:(NSString *)originalTransactionID; + +- (void)refundReversalWithAmount:(NSInteger)amount + currency:(NSString *)currency + originalTransactionID:(NSString *)originalTransactionID; + +- (void)connectToAddress:(NSString *)address; + +- (void)setLogLevel:(eLogLevel)logLevel; + +- (void)getDeviceLogs; + +- (void)getPendingTransaction; + +- (void)update; + +- (void)listDevices; + +@end +```` + +## HandpointModule + +**HandpointModule.m** + +````objectivec +#import "" +#import "HandpointModule.h" +#import "HeftRemoteDevice+SendableDevice.h" +#import "SDKEvent.h" +#import "ConnectionStatus.h" +#import "Currency.h" +#import "CDVInvokedUrlCommand+Arguments.h" +#import "StatusInfo.h" +#import "TransactionResult.h" + +typedef NS_ENUM(NSInteger, ConnectionStatus) +{ + ConnectionStatusNotConfigured, + ConnectionStatusConnected, + ConnectionStatusConnecting, + ConnectionStatusDisconnected, + ConnectionStatusDisconnecting, + ConnectionStatusInitializing +}; + +@interface HandpointModule () + +@property (nonatomic) HeftManager* manager; +@property (nonatomic, strong) id api; +@property (nonatomic) NSString *ssk; +@property (nonatomic) HeftRemoteDevice* preferredDevice; +@property (nonatomic) NSString *eventHandlerCallbackId; +@property (nonatomic) NSMutableDictionary *devices; + +@end + +@implementation HandpointModule + +- (instancetype)initWithSharedSecret:(NSString *)sharedSecret +{ + NSLog(@"\n\tpluginInitialize"); + self.manager = [HeftManager sharedManager]; + self.manager.delegate = self; + self.devices = [@{} mutableCopy]; + + [self fillDevicesFromConnectedCardReaders]; + + self.ssk = sharedSecret; +} + +- (void)saleWithAmount:(NSInteger)amount + currency:(NSString *)currency +{ + BOOL result = [self.api saleWithAmount:amount + currency:currency + cardholder:YES]; + + if (result == false) + { + //Do something + } +} + +- (void)refundWithAmount:(NSInteger)amount + currency:(NSString *)currency +{ + BOOL result = [self.api refundWithAmount:amount + currency:currency + cardholder:YES] + + if (result == false) + { + //Do something + } +} + +- (void)saleReversalWithAmount:(NSInteger)amount + currency:(NSString *)currency + originalTransactionID:(NSString *)originalTransactionID +{ + BOOL result = [self.api saleVoidWithAmount:amount + currency:currency + cardholder:YES + transaction:originalTransactionID]; + + if (result == false) + { + //Do something + } +} + +- (void)refundReversalWithAmount:(NSInteger)amount + currency:(NSString *)currency + originalTransactionID:(NSString *)originalTransactionID +{ + BOOL result = [self.api refundVoidWithAmount:amount + currency:currency + cardholder:YES + transaction:originalTransactionID]; + + if (result == false) + { + //Do something + } +} + +#pragma mark - Device Management + +- (void)connectToAddress:(NSString *)address +{ + HeftRemoteDevice *remoteDevice = self.devices[address]; + + if (remoteDevice) + { + BOOL isRemoteDeviceSameAsPreferred = self.preferredDevice && + [self.preferredDevice.address isEqualToString:remoteDevice.address]; + + // If we are already connected to this device, update shared secret + if (self.api && isRemoteDeviceSameAsPreferred) + { + // Already connected to device + } + else + { + self.preferredDevice = remoteDevice; + + [self.manager clientForDevice:remoteDevice + sharedSecret:self.ssk + delegate:self]; + } + + [self connectionStatusChanged:ConnectionStatusConnecting]; + } + else + { + NSLog(@"Can't connect. No device available. Have you searched?"); + } +} + +- (void)setLogLevel:(eLogLevel)logLevel +{ + [self.api logSetLevel:logLevel]; +} + +- (void)getDeviceLogs +{ + [self.api logGetInfo]; +} + +- (void)getPendingTransaction +{ + BOOL success = NO; + + if ([self.api isTransactionResultPending]) + { + success = [self.api retrievePendingTransaction]; + } + + if (success) + { + //... + } + else + { + //... + } +} + +- (void)update +{ + [self.api financeInit]; +} + +- (void)listDevices +{ + NSArray* devices = [self.manager connectedCardReaders]; + + /** + * A device can have four levels of connection: unpaired, paired, + * connected and connected in the SDK. + * + * Due to the nature of the iOS ExternalAccessory framework, + * devices that are already connected at an iOS level will not appear in a normal search, + * as they already appear through the "connectedCardReaders" array in the manager + * (Yeah, I know) + * + * So the "if" takes care of differentiating those two cases + * + * If we have device(s) connected we just go for those, otherwise, search. + */ + + if(devices.count) + { + //We have device(s) already connected, we skip the search. + for (HeftRemoteDevice *device in devices) + { + [self addDevice:device]; + } + + [self didDiscoverFinished]; + } + else + { + //We search and wait... + [self.manager startDiscovery]; + } +} + +# pragma mark - Callbacks + +- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice +{ + [self addDevice:newDevice]; +} + +- (void)didLostAccessoryDevice:(HeftRemoteDevice *)oldDevice +{ + [self removeDevice:oldDevice]; + + if(self.preferredDevice && self.preferredDevice.address == oldDevice.address) + { + [self connectionStatusChanged:ConnectionStatusDisconnected]; + + self.preferredDevice = nil; + } +} + +- (void)didDiscoverFinished +{ + [self fillDevicesFromConnectedCardReaders]; + + for (NSString *key in [self.devices allKeys]) + { + HeftRemoteDevice *device = self.devices[key]; + + if ([device.address isEqualToString:]) + { + //Do something with the device if it's the same one you expect. + break; + } + } +} + +- (void)didConnect:(id )client +{ + if(client) + { + self.api = client; + + [self connectionStatusChanged:ConnectionStatusConnected]; + } +} + +- (void)connectionStatusChanged:(ConnectionStatus)status +{ + //Here you get notified of connection status changes +} + +- (NSString *)stringFromConnectionStatus:(ConnectionStatus)status +{ + switch(status) + { + case ConnectionStatusNotConfigured: + return @"NotConfigured"; + case ConnectionStatusConnected: + return @"Connected"; + case ConnectionStatusConnecting: + return @"Connecting"; + case ConnectionStatusDisconnected: + return @"Disconnected"; + case ConnectionStatusDisconnecting: + return @"Diconnecting"; + case ConnectionStatusInitializing: + return @"Initializing"; + } +} + +- (void)responseStatus:(id )info +{ + //Here you'll get status updates during the transaction +} + +- (void)responseError:(id )info +{ + //Here if something went wrong +} + +- (void)responseFinanceStatus:(id )info +{ + //Here's the result of your transaction +} + +- (void)responseLogInfo:(id )info +{ + NSLog(@"\n\tresponseLogInfo: %@", info.status); +} + +- (void)requestSignature:(NSString *)receipt +{ + [self.api acceptSignature:YES]; +} + +- (void)addDevice:(HeftRemoteDevice *)device +{ + self.devices[device.address] = device; +} + +- (void)removeDevice:(HeftRemoteDevice *)device +{ + if (self.devices[device.address]) + { + [self.devices removeObjectForKey:device.address]; + } +} + +- (void)fillDevicesFromConnectedCardReaders +{ + for (HeftRemoteDevice *device in [self.manager connectedCardReaders]) + { + [self addDevice:device]; + } +} + +@end +```` diff --git a/ios_versioned_docs/version-iOS SDK 4.0.2/iostransactions.md b/ios_versioned_docs/version-iOS SDK 4.0.2/iostransactions.md new file mode 100644 index 0000000..a0fd2bb --- /dev/null +++ b/ios_versioned_docs/version-iOS SDK 4.0.2/iostransactions.md @@ -0,0 +1,582 @@ +--- +sidebar_position: 8 +id: iostransactions +--- + + + +# Transaction Types + +## Sale{#2} + +`saleWithAmount` Method + +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 a map with optional parameters. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency ` Required
*NSString* | 3 letter currency code in accordance to ISO4217| +| `options`
*SaleOptions* | An object to store all the customization options for a sale.| + +**Code example** + +````objectivec +//If you just need a plain vanilla sale: +[api saleWithAmount:100 + currency:Currency.EUR.alpha]; + +//But you can customize your sale: +SaleOptions *options = [SaleOptions new]; +//Optionally +options.customerReference = @"Your customer reference"; +//If you need Multi MID / Custom merchant Authentication: +MerchantAuth *auth = [MerchantAuth new]; +Credential *cred = [Credential new]; +//Optionally +cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; +//Optionally +cred.mid = @"mid"; +//Optionally +cred.tid = @"tid"; +//Add as many credentials as Acquirers your merchant have agreements with +[auth add:cred]; +options.merchantAuth = auth; +//If you want to specify the budget period +//Only available for SureSwipe/Altech +//Here it's 3 months +options.divideByMonths = @"3"; + +[api saleWithAmount:100 + currency:Currency.EUR.alpha + options:options]; +```` + +**Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** +[**requestSignature**](iosevents.md#17) + +Invoked if card verification requires signature. +*** +[**responseFinanceStatus **](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + +## Sale And Tokenize Card{#4} + +`saleAndTokenizeCardWithAmount` Method + +A sale and tokenize operation initiates a payment operation with the payment terminal. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*NSString* | 3 letter currency code in accordance to ISO4217| +| `options`
*SaleOptions* | An object to store all the customization options for a sale.| + +**Code example** + +````objectivec +//If you just need a plain vanilla sale tokenization: +[api saleAndTokenizeWithAmount:100 + currency:Currency.EUR.alpha]; + +//But you can customize your sale: +SaleOptions *options = [SaleOptions new]; +//Optionally +options.customerReference = @"Your customer reference"; +//If you need Multi MID / Custom merchant Authentication: +MerchantAuth *auth = [MerchantAuth new]; +Credential *cred = [Credential new]; +//Optionally +cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; +//Optionally +cred.mid = @"mid"; +//Optionally +cred.tid = @"tid"; +//Add as many credentials as Acquirers your merchant have agreements with +[auth add:cred]; +options.merchantAuth = auth; +//If you want to specify the budget period +//Only available for SureSwipe/Altech +//Here it's 3 months +options.divideByMonths = @"3"; + +[api saleAndTokenizeWithAmount:100 + currency:Currency.EUR.alpha + options:options]; +```` + +**Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**requestSignature**](iosevents.md#17) + +Invoked if card verification requires signature. +*** + +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + +## Sale Reversal{#3} + +`saleVoidWithAmount` Method + +Request a void of a previous sale transaction. Amount, currency and transactionID of the original sale must be sent as parameters. This operation reverts (if possible) a specific sale identified with a transaction id. Note that transactions can only be reversed the same day as when the transaction was made. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*NSString* | 3 letter currency code in accordance to ISO4217 | +| `transaction` Required
*NSString* | TransactionID of the sale transaction to be voided | +| `options`
*Options* | An object to store all the customization options for this operation.| + +**Code example** + +```objectivec +//If you just need a plain vanilla sale reversal: +[api saleReversalWithAmount:100 + currency:Currency.EUR.alpha + transactionId:originalTransactionID + options:options]; + +//But you can customize your reversal: +Options *options = [Options new]; +//Optionally +options.customerReference = @"Your customer reference"; + +[api saleReversalWithAmount:100 + currency:Currency.EUR.alpha + transactionId:@"00000000-0000-0000-0000-000000000000" + options:options]; +``` + +**Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** +[**responseError **](iosevents.md#15) + +Invoked when an error response happens. +*** +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + +## Refund{#5} + +`refundWithAmount` Method + +A refund initiates a refund operation with the payment terminal. This operation moves funds from the merchant account to the cardholder's card. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*NSString* | Currency of the charge| +| `transaction` Required
*NSString* | If present it links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.| +| `options`
*MerchantAuthOptions* | An object to store all the customization options for a refund.| + +**Code example** + +````objectivec +//If you just need a plain vanilla refund: +[api refundWithAmount:100 + currency:Currency.EUR.alpha + transaction:@"00000000-0000-0000-0000-000000000000"]; + +//But you can customize your sale: +MerchantAuthOptions *options = [MerchantAuthOptions new]; +//Optionally +options.customerReference = @"Your customer reference"; +//If you need Multi MID / Custom merchant Authentication: +MerchantAuth *auth = [MerchantAuth new]; +Credential *cred = [Credential new]; +//Optionally +cred.acquirer = [Credential getAcquirerFromString:@"acquirer"]; +//Optionally +cred.mid = @"mid"; +//Optionally +cred.tid = @"tid"; +//Add as many credentials as Acquirers your merchant have agreements with +[auth add:cred]; +options.merchantAuth = auth; + +[api refundWithAmount:100 + currency:Currency.EUR.alpha + transaction:@"00000000-0000-0000-0000-000000000000" + options:options]; +```` + +** Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + + +## Refund reversal{#6} + +`refundVoidWithAmount` Method + +Request a void of a previous refund transaction. Amount, currency and transactionID of the original refund must be sent as parameters. This operation reverts (if possible) a specific refund identified with a transaction id. Note that transactions can only be reversed the same day as when the transaction was made. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*NSInteger* | Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
*NSString* | 3 letter currency code in accordance to ISO4217| +| `transaction` Required
*NSString* | TransactionID of the refund transaction to be voided| +| `options`
*Options* | An object to store all the customization options for this operation.| + +**Code example** + +````objectivec +//If you just need a plain vanilla refund reversal: +[api refundReversalWithAmount:100 + currency:Currency.EUR.alpha + transactionId:originalTransactionID + options:options]; + +//But you can customize your sale: +Options *options = [Options new]; +//Optionally +options.customerReference = @"Your customer reference"; + +[api refundReversalWithAmount:100 + currency:Currency.EUR.alpha + transactionId:@"00000000-0000-0000-0000-000000000000" + options:options]; +```` + +** Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if the operation was successfully sent to device.| + +## Tokenize Card{#10} + +`tokenizeCard` Method + +Initiates a card tokenization operation with the payment terminal (not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice). + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `reference` Required
*NSString* | string for customer reference| + + +**Code example** + +````objectivec +//Initiates a card tokenization operation. +[heftClient tokenizeCard]; +```` + + +** Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. + +*** + +[**requestSignature**](iosevents.md#17) + +Invoked if card verification requires signature. + +*** + +[**responseRecoveredTransactionStatus**](iosevents.md#44) + +Invoked when the card reader finishes processing the transaction. + +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + +## Accept signature{#7} + +`acceptSignature` Method + +A [*requestSignature*](iosevents.md#17) event is invoked during a transaction if signature verification is needed. The merchant is required to ask the cardholder for signature and approve (or decline) the signature. signatureRequired lets the payment terminal know if the signature was approved (by passing YES to the function) or declined by the merchant (by passing NO to the function). + +**Parameters** + +| Parameter | Notes | +| ----------- | ----------- | +| `flag` Required
*Boolean* | YES if signature is valid, NO otherwise| + + +**Code example** + +````objectivec +//acceptSignature: +//Inform the card reader if signature is valid or not +-(IBAction)accept +{ + [heftClient acceptSignature:YES]; +} +-(IBAction)decline +{ + [heftClient acceptSignature:NO]; +} +```` + +** Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**responseFinanceStatus**](iosevents.md#16) + +Invoked when the payment terminal finishes processing the transaction. +*** + +## Retrieve Pending Transaction{#8} + +`retrievePendingTransaction` Method + +Retrieving a pending transaction fetches a transaction result that was lost due to an unexpected disconnection between the payment terminal and the associated application. + +**Code example** + +````objectivec +//retrievePendingTransaction: +//Called when a pending transaction is discovered upon connecting to a specific card reader +- (void)didConnect:(id)client{ + heftClient = client; + + if(heftClient){ + if([heftClient isTransactionResultPending] == YES) { + // a pending transaction has been detected ... + // ... so, lets get it + [heftClient retrievePendingTransaction]; + } + } +} +```` + +** Events invoked** + +[**responseStatus**](iosevents.md#14) + +Invoked during a transaction with different statuses from the payment terminal. +*** + +[**responseError**](iosevents.md#15) + +Invoked when an error response happens. +*** + +[**responseRecoveredTransactionStatus**](iosevents.md#44) + +Invoked when the card reader has returned a recovered transaction. +*** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `YES` if operation starts successfully.| + +

+ +**Notes** + +***On starting a new transaction*** + +If a new transaction is started without fetching first a pending transaction result, then the pending transaction result will be discarded. +*** + +***User notifications while a transaction result is pending*** + +The payment terminal will not give any visible indication that a transaction result is pending. +*** + +***User notifications when fetching a pending transaction result*** + +The payment terminal will briefly display a message when a pending transaction result is recovered. +*** + +## Tip Adjustment{#9} + +`tipAdjustment` Method + +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. +The tip adjustment method does not rely on a card reader and is therefore a separate method that must be initialized with a shared secret. The function is defined in the file HapiRemoteService.h +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. This functionality is limited to HiLite terminals. + + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `tipAmount` Required
*NSInteger* | Tip amount added to the original (base) transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `transaction` Required
*NSString* | TransactionID (GUID) of the original sale transaction to be adjusted| + + +**Code example** + +````objectivec +//First, you need to include the following dependency +#include "HapiRemoteService.h" + +//Second, the shared secret needs to be initialized +NSString* shared_secret = @"0102030405060708091011121314151617181920212223242526272829303132"; +BOOL result = setupHandpointApiConnection(shared_secret); + +//Third, you need to retrieve the unique transaction id of the original sale transaction you want to adjust. The below GUID is only an example and will result in a decline from the host if used for tip adjustment +NSString* transaction = @"d50af540-a1b0-11e6-85e6-07b2a5f091ec"; + +//Fourth, let's tip adjust a transaction for $10.00! +-(IBAction)tipAdjustment:(UIButton*) sender +{ + BOOL result = tipAdjustment(transaction, 1000, ^(TipAdjustmentStatus status) + { + if(status == TipAdjustmentAuthorised) { + + //Successfully adjusted! + + } + + else if(status == TipAdjustmentDeclined) { + + //Declined! + + } + + else if(status == TipAdjustmentFailed) { + + //Timeout! + + } + }); +} +```` + +**Returns** + +Result of the tip adjustment transaction, possible values : + +| Parameter | Notes | +| ----------- | ----------- | +| **status**| - **TipAdjustmentAuthorised** (tip adjustment approved by the processor)
- **TipAdjustmentFailed** (system error or timeout)
- **TipAdjustmentDeclined** (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. diff --git a/ios_versioned_sidebars/version-iOS SDK 4.0.2-sidebars.json b/ios_versioned_sidebars/version-iOS SDK 4.0.2-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/ios_versioned_sidebars/version-iOS SDK 4.0.2-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/ios_versions.json b/ios_versions.json index 4c1ba60..24dc27b 100644 --- a/ios_versions.json +++ b/ios_versions.json @@ -1,4 +1,5 @@ [ + "iOS SDK 4.0.2", "iOS SDK 4.0.1", "iOS SDK 4.0.0" ] diff --git a/javascript/javascriptreleasenotes.md b/javascript/javascriptreleasenotes.md index 7245f13..93db530 100644 --- a/javascript/javascriptreleasenotes.md +++ b/javascript/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.2.0 diff --git a/javascript_versioned_docs/version-JavaScript SDK 6.0.1/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 6.0.1/javascriptreleasenotes.md index 0043ffd..0031baa 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 6.0.1/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 6.0.1/javascriptreleasenotes.md @@ -8,7 +8,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/javascript_versioned_docs/version-JavaScript SDK 6.1.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 6.1.0/javascriptreleasenotes.md index 1e9ba30..7a64d95 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 6.1.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 6.1.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/javascript_versioned_docs/version-JavaScript SDK 6.2.1/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 6.2.1/javascriptreleasenotes.md index f1e51ab..15011a8 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 6.2.1/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 6.2.1/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/javascript_versioned_docs/version-JavaScript SDK 6.3.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 6.3.0/javascriptreleasenotes.md index f8a2876..7d657da 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 6.3.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 6.3.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 6.3.0 diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.0.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.0.0/javascriptreleasenotes.md index a5fc7d3..9fc1345 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 7.0.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 7.0.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.0.0 diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.1.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.1.0/javascriptreleasenotes.md index 992b6d5..8ad8e53 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 7.1.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 7.1.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.1.0 diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.0/javascriptreleasenotes.md index 7245f13..93db530 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 7.2.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.2.0 diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptobjects.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptobjects.md index 58bed4b..41603b5 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptobjects.md +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptobjects.md @@ -399,7 +399,7 @@ An object to store the customization options for a refund. This object can be em | 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#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature.| +| `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).| @@ -461,7 +461,7 @@ An object to store the customization options for a sale operation. This object c | 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#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information.| +| `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.| diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptreleasenotes.md index 9fbb952..d79c048 100644 --- a/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.2/javascriptreleasenotes.md @@ -6,13 +6,13 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 7.2.2 **Features:** -A new `tokenize` parameter is available under [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). See [Android SDK 7.1009.5](/android/androidreleasenotes#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature. +A new `tokenize` parameter is available under [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). 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. ## 7.2.0 **Features:** diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptintroduction.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptintroduction.md new file mode 100644 index 0000000..baa4147 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptintroduction.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 1 +id: javascriptintroduction +--- + + + +# Introduction {#javascriptIntro} + +
+
+
+

JavaScript SDK

+
+
+ + + +
+
+ Get the latest 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. + +![Sandbox logo](/img/jsoverview.png) + diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptobjects.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptobjects.md new file mode 100644 index 0000000..2f6b120 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptobjects.md @@ -0,0 +1,823 @@ +--- +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` + + +## Reversal Options{#40} + +`ReversalOptions` Object + +An object to store the customization options for a reversal. 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".| +| `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.| +| `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" + } +} +``` + + +## 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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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| +| `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.3/javascriptprocessingpayments.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptprocessingpayments.md new file mode 100644 index 0000000..e12bddd --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/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.3/javascriptquickintegration.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptquickintegration.md new file mode 100644 index 0000000..f5c935d --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/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 + + + + + Handpoint SDK Trial Integration + + + + + + + + + +``` + +:::tip +Maintain the connection with the terminal at all times: +- To be able to recover a transaction result through the callback passed in the [*init*](javascriptterminalmanagement.md#1) method, the point of sale and the terminal **MUST** be connected and online. For that reason, we recommend to connect to the target terminal and maintain the connection alive at all times instead of connecting and disconnecting for every transaction. +- Using the same connection, the user may perform as many transactions as desired. The SDK is in charge of maintaining the secure channel between the point of sale and the terminal. No connection and disconnection between transactions is required. The silent connected periods will provide the possibility for the device to deliver any pending transaction result in case of a network issue. + +How Transaction Recovery Works: +- The terminal has a transaction recovery loop to automatically send back the pending [*Transaction Result*](javascriptobjects.md#18) to the Point of sale 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 point of sale 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 anytime the startRecovery method is used. +::: \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptreleasenotes.md new file mode 100644 index 0000000..595b4d1 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptreleasenotes.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 2 +id: javascriptreleasenotes +--- + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 7.2.3 +**Features:** + +A new `cardPresent` parameter is available under [ReversalOptions](javascriptobjects.md#40). 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. + +## 7.2.2 +**Features:** + +A new `tokenize` parameter is available under [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). 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. + +## 7.2.0 +**Features:** + +We're excited to announce the latest update to our JavaScript 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](javascriptobjects.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. + + +## 7.1.0 +**Features**: + +We are introducing a new transaction type called [Pre-Authorization](javascripttransactiontypes#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](javascripttransactiontypes#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](javascripttransactiontypes#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](javascripttransactiontypes#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. + +## 7.0.0 +**BREAKING CHANGE:** + +We are introducing a new feature called [Get Transaction Status](javascriptterminalmanagement.md#17). 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](javascriptobjects.md#operation-start-result) 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. + + +When starting a new financial operation (sale, refund etc.) the `OperationStartResult` object will contain two new attributes: +- `transactionReference`: This universally unique identifier (UUID v4) will allow you to query the Handpoint gateway directly to know the outcome of the transaction. This feature is to be used in case there is a connection issue or any other problem preventing the terminal from delivering the end of transaction to your software. +- `transactionResult`: Promise that will resolve/reject with the [Transaction Result](javascriptobjects.md#18) object. + +## 6.3.0 + +**Features**: + +We are introducing a new feature called [Transaction Metadata](javascriptobjects.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. + +## 6.2.1 + +**Fixes**: +- Reconnection management. + +## 6.2.1 + +**Fixes**: +- Reconnection management. + +## 6.2.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. You do not need to update to v6.2.0 to benefit from this new feature. v6.2.0 will only allow you to disable the duplicate payment check feature if you wish to not support it. + +The new `duplicate_check` parameter is available under the [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). + +## 6.1.0 + +**Features**: +- Mail order/Telephone order (MoTo) + +**Fixes**: +- Duplications on recovered transactions + +## 6.0.1 + +**Features**: +- Internal variable handling + +## 6.0.0 + +**BREAKING CHANGE:** +- The recovery function in the init method was added to make sure that ALL transaction results are received by the POS, even in case of an unstable network connection. The recovery function passed as third parameter in the init method MUST return a promise. The resolution of the promise will send a message to the payment terminal acknowledging the reception of the transaction result. diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptsandbox.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptsandbox.md new file mode 100644 index 0000000..576ac23 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptsandbox.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 5 +id: javascriptsandbox +--- + + +# 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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptterminalmanagement.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptterminalmanagement.md new file mode 100644 index 0000000..8bdae19 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascriptterminalmanagement.md @@ -0,0 +1,262 @@ +--- +sidebar_position: 7 +id: javascriptterminalmanagement +--- + + +# Terminal Management + +## Initialize{#1} + +`Initialize` Method + +Initializes the JavaScript SDK and returns the list of payment terminals associated with the account. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `API_key` Required
*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.3/javascripttransactiontypes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/javascripttransactiontypes.md new file mode 100644 index 0000000..7c2d213 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.3/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.| +| `reversalOptions`
[*ReversalOptions*](javascriptobjects.md#40) | 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.| +| `reversalOptions`
[*ReversalOptions*](javascriptobjects.md#40) | 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_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

+
+
+ + + +
+
+ Get the latest 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. + +![Sandbox logo](/img/jsoverview.png) + 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* | List of percentages used to calculate the tip amount. **REQUIRED**| +| `enterAmountEnabled`
*Boolean* | Flag used to enable the cardholder to manually enter the tip amount. Default: true| +| `skipEnabled`
*Boolean* | Flag used to enable the cardholder to skip the tipping step. Default: true| +| `footer`
*String* | Footer note which will appear on the tipping menu. Default: Empty string| + +**Code example** + +```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 + + + + + Handpoint SDK Trial Integration + + + + + + + + + +``` + +:::tip +Maintain the connection with the terminal at all times: +- To be able to recover a transaction result through the callback passed in the [*init*](javascriptterminalmanagement.md#1) method, the point of sale and the terminal **MUST** be connected and online. For that reason, we recommend to connect to the target terminal and maintain the connection alive at all times instead of connecting and disconnecting for every transaction. +- Using the same connection, the user may perform as many transactions as desired. The SDK is in charge of maintaining the secure channel between the point of sale and the terminal. No connection and disconnection between transactions is required. The silent connected periods will provide the possibility for the device to deliver any pending transaction result in case of a network issue. + +How Transaction Recovery Works: +- The terminal has a transaction recovery loop to automatically send back the pending [*Transaction Result*](javascriptobjects.md#18) to the Point of sale 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 point of sale 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 anytime the startRecovery method is used. +::: \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptreleasenotes.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptreleasenotes.md new file mode 100644 index 0000000..f782033 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptreleasenotes.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 2 +id: javascriptreleasenotes +--- + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 7.2.4 +**Features:** + +The batch number is returned in the Transaction Result object now as `batchNumber`, provided the acquirer returns it. Please see [Transaction Result Object](javascriptobjects.md#18) + +## 7.2.3 +**Features:** + +A new `cardPresent` parameter is available under [ReversalOptions](javascriptobjects.md#40). 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. + +## 7.2.2 +**Features:** + +A new `tokenize` parameter is available under [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). 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. + +## 7.2.0 +**Features:** + +We're excited to announce the latest update to our JavaScript 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](javascriptobjects.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. + + +## 7.1.0 +**Features**: + +We are introducing a new transaction type called [Pre-Authorization](javascripttransactiontypes#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](javascripttransactiontypes#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](javascripttransactiontypes#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](javascripttransactiontypes#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. + +## 7.0.0 +**BREAKING CHANGE:** + +We are introducing a new feature called [Get Transaction Status](javascriptterminalmanagement.md#17). 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](javascriptobjects.md#operation-start-result) 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. + + +When starting a new financial operation (sale, refund etc.) the `OperationStartResult` object will contain two new attributes: +- `transactionReference`: This universally unique identifier (UUID v4) will allow you to query the Handpoint gateway directly to know the outcome of the transaction. This feature is to be used in case there is a connection issue or any other problem preventing the terminal from delivering the end of transaction to your software. +- `transactionResult`: Promise that will resolve/reject with the [Transaction Result](javascriptobjects.md#18) object. + +## 6.3.0 + +**Features**: + +We are introducing a new feature called [Transaction Metadata](javascriptobjects.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. + +## 6.2.1 + +**Fixes**: +- Reconnection management. + +## 6.2.1 + +**Fixes**: +- Reconnection management. + +## 6.2.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. You do not need to update to v6.2.0 to benefit from this new feature. v6.2.0 will only allow you to disable the duplicate payment check feature if you wish to not support it. + +The new `duplicate_check` parameter is available under the [SaleOptions](javascriptobjects.md#23) and [RefundOptions](javascriptobjects.md#24). + +## 6.1.0 + +**Features**: +- Mail order/Telephone order (MoTo) + +**Fixes**: +- Duplications on recovered transactions + +## 6.0.1 + +**Features**: +- Internal variable handling + +## 6.0.0 + +**BREAKING CHANGE:** +- The recovery function in the init method was added to make sure that ALL transaction results are received by the POS, even in case of an unstable network connection. The recovery function passed as third parameter in the init method MUST return a promise. The resolution of the promise will send a message to the payment terminal acknowledging the reception of the transaction result. diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptsandbox.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptsandbox.md new file mode 100644 index 0000000..576ac23 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptsandbox.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 5 +id: javascriptsandbox +--- + + +# 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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptterminalmanagement.md b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptterminalmanagement.md new file mode 100644 index 0000000..9a7c809 --- /dev/null +++ b/javascript_versioned_docs/version-JavaScript SDK 7.2.4/javascriptterminalmanagement.md @@ -0,0 +1,262 @@ +--- +sidebar_position: 7 +id: javascriptterminalmanagement +--- + + +# Terminal Management + +## Initialize{#1} + +`Initialize` Method + +Initializes the JavaScript SDK and returns the list of payment terminals associated with the account. + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `API_key` Required
*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_docs/version-Javascript SDK 6.2.0/javascriptreleasenotes.md b/javascript_versioned_docs/version-Javascript SDK 6.2.0/javascriptreleasenotes.md index 2ba0e6b..fe55a64 100644 --- a/javascript_versioned_docs/version-Javascript SDK 6.2.0/javascriptreleasenotes.md +++ b/javascript_versioned_docs/version-Javascript SDK 6.2.0/javascriptreleasenotes.md @@ -6,7 +6,7 @@ id: javascriptreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/javascript_versioned_sidebars/version-JavaScript SDK 7.2.3-sidebars.json b/javascript_versioned_sidebars/version-JavaScript SDK 7.2.3-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/javascript_versioned_sidebars/version-JavaScript SDK 7.2.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} 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 04d3f90..4a9a8b1 100644 --- a/javascript_versions.json +++ b/javascript_versions.json @@ -1,4 +1,6 @@ [ + "JavaScript SDK 7.2.4", + "JavaScript SDK 7.2.3", "JavaScript SDK 7.2.2", "JavaScript SDK 7.2.0", "JavaScript SDK 7.1.0", diff --git a/restapi/restendpoints.md b/restapi/restendpoints.md index d9dfd31..163cdf3 100644 --- a/restapi/restendpoints.md +++ b/restapi/restendpoints.md @@ -22,7 +22,7 @@ Initializes the REST API client and returns the list of payment terminals associ | Parameter | Notes | | ----------- | ----------- | -| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. | +| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. (UNIQUE per Merchant) | Returns @@ -51,14 +51,15 @@ RESPONSE: { "merchant_id_alpha": "merchantID", "serial_number": "082104578", - "customerReference": "op15248", + "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) +::: @@ -76,7 +77,7 @@ POST endpoint used to send a financial operation to the payment terminal. The tr | Parameter | Notes | | ----------- | ----------- | -| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. | +| `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. | @@ -92,6 +93,9 @@ POST endpoint used to send a financial operation to the payment terminal. The tr **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: @@ -164,7 +168,7 @@ GET endpoint used to retrieve transaction results from the payment terminal. In | Parameter | Notes | | ----------- | ----------- | -| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant. | +| `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. | @@ -270,7 +274,7 @@ Note: If two tip adjustments are sent for the same original transaction, only th | Parameter | Notes | | ----------- | ----------- | -| `Header: ApiKeyCloud` Required
*String* | Api key used to authenticate the merchant.| +| `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. | @@ -354,8 +358,13 @@ The main transaction result [*FinancialStatus*](restobjects.md#financialStatus) | Parameter | Notes | | ----------- | ----------- | -| `Header: ApiKeyCloud` Required *String* | Api key used to authenticate the 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. | +| `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** @@ -436,21 +445,30 @@ The `https://transactions.handpoint.io/transactions/{transactionReference}/statu **Selector Values** | Selector | Description | -| ----------- | ----------- | -| all |Returns the status of all transactions associated with the given `transactionReference`. | -| {index} |Returns the status of a specific transaction identified by its index in the sequence of transactions associated with the `transactionReference`. The index is a 1-based integer, where 1 represents the first transaction, 2 the second, and so on.| +| ------------- | ----------- | +| 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. | -| `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.| +| `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** @@ -478,4 +496,251 @@ The `https://transactions.handpoint.io/transactions/{transactionReference}/statu curl -X GET \ -H "ApiKeyCloud: your-api-key" \ "https://transactions.handpoint.io/transactions/123e4567-e89b-12d3-a456-426614174000/status/3" - ``` \ No newline at end of file + ``` + +## 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/restobjects.md b/restapi/restobjects.md index 68af6f1..c6942dd 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -15,7 +15,7 @@ An enum representing the supported acquirers for merchant authentication. **Possible values** -`AMEX` `BORGUN` `EVO` `OMNIPAY` `POSTBRIDGE` `INTERAC` `TSYS` `VANTIV` `SANDBOX` +`AMEX` `BORGUN` `OMNIPAY` `POSTBRIDGE` `TSYS` `VANTIV` `SANDBOX` ## Balance @@ -317,7 +317,7 @@ An enum representing different types of operations. Possible Values: -`sale` `refund` `refundReversal` `saleReversal` `saleAndTokenizeCard` `tokenizeCard` `printReceipt` `update` `cardPan` `pingDevice` `stopCurrentTransaction` `moToSale` `moToRefund` `moToReversal` `moToPreAuthorization` `preAuthorization` `preAuthorizationIncrease` `preAuthorizationCapture` `preAuthorizationReversal` +`sale` `refund` `refundReversal` `saleReversal` `saleAndTokenizeCard` `tokenizeCard` `printReceipt` `cardPan` `pingDevice` `stopCurrentTransaction` `moToSale` `moToRefund` `moToReversal` `moToPreAuthorization` `preAuthorization` `preAuthorizationIncrease` `preAuthorizationCapture` `preAuthorizationReversal` @@ -335,9 +335,8 @@ Possible Values: | `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)** | -| `update`
*String* | The update operation checks for new software or configuration updates and initiates a download if required. | | `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 online. | +| `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. | @@ -570,6 +569,8 @@ An object to store information about the request sent to the payment terminal. | `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** @@ -660,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 @@ -681,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)| @@ -822,19 +824,3 @@ An enum representing the possible verification methods used during the transacti Possible values: `UNDEFINED` `SIGNATURE` `PIN` `PIN_SIGNATURE` `FAILED` `NOT_REQUIRED` `MOBILE_PASS_CODE` - - - - - - - - - - - - - - - - diff --git a/restapi/restreleasenotes.md b/restapi/restreleasenotes.md index 1224d76..5b1b534 100644 --- a/restapi/restreleasenotes.md +++ b/restapi/restreleasenotes.md @@ -6,9 +6,43 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +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:** diff --git a/restapi_versioned_docs/version-REST API 2.10.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.10.0/restreleasenotes.md index c657c23..ab41277 100644 --- a/restapi_versioned_docs/version-REST API 2.10.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.10.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.10.0 diff --git a/restapi_versioned_docs/version-REST API 2.12.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.12.0/restreleasenotes.md index 58acd2e..1eeab45 100644 --- a/restapi_versioned_docs/version-REST API 2.12.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.12.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/restapi_versioned_docs/version-REST API 2.13.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.13.0/restreleasenotes.md index 8e24f93..75a7656 100644 --- a/restapi_versioned_docs/version-REST API 2.13.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.13.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.13.0 diff --git a/restapi_versioned_docs/version-REST API 2.14.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.14.0/restreleasenotes.md index 9880b1b..cd9971b 100644 --- a/restapi_versioned_docs/version-REST API 2.14.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.14.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.14.0 diff --git a/restapi_versioned_docs/version-REST API 2.15.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.15.0/restreleasenotes.md index 7a45b5b..6969b42 100644 --- a/restapi_versioned_docs/version-REST API 2.15.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.15.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/restapi_versioned_docs/version-REST API 2.17.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.17.0/restreleasenotes.md index 532b68c..23d381a 100644 --- a/restapi_versioned_docs/version-REST API 2.17.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.17.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.17.0 diff --git a/restapi_versioned_docs/version-REST API 2.20.0/restobjects.md b/restapi_versioned_docs/version-REST API 2.20.0/restobjects.md index c31f099..798a41e 100644 --- a/restapi_versioned_docs/version-REST API 2.20.0/restobjects.md +++ b/restapi_versioned_docs/version-REST API 2.20.0/restobjects.md @@ -569,7 +569,7 @@ An object to store information about the request sent to the payment terminal. | `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#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information.| +| `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.| **Code example** diff --git a/restapi_versioned_docs/version-REST API 2.20.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.20.0/restreleasenotes.md index 83cf468..391d376 100644 --- a/restapi_versioned_docs/version-REST API 2.20.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.20.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.20.0 @@ -16,7 +16,7 @@ Added a selector to the [{transactionReference}/status](restendpoints.md#transac 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#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature. +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:** diff --git a/restapi_versioned_docs/version-REST API 2.22.2/assets/postmanCollection.png b/restapi_versioned_docs/version-REST API 2.22.2/assets/postmanCollection.png new file mode 100644 index 0000000..ec43e6e Binary files /dev/null and b/restapi_versioned_docs/version-REST API 2.22.2/assets/postmanCollection.png differ diff --git a/restapi_versioned_docs/version-REST API 2.22.2/restdownloads.md b/restapi_versioned_docs/version-REST API 2.22.2/restdownloads.md new file mode 100644 index 0000000..653b02c --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/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.22.2/restendpoints.md b/restapi_versioned_docs/version-REST API 2.22.2/restendpoints.md new file mode 100644 index 0000000..163cdf3 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/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. + +![getTrxStatusEndpoint](/img/getTransactionStatusEndpoint.drawio.png) + +**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.22.2/restintroduction.md b/restapi_versioned_docs/version-REST API 2.22.2/restintroduction.md new file mode 100644 index 0000000..5252785 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/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**. + + + + +![Sandbox logo](/img/RestApiDiagram) + + diff --git a/restapi_versioned_docs/version-REST API 2.22.2/restobjects.md b/restapi_versioned_docs/version-REST API 2.22.2/restobjects.md new file mode 100644 index 0000000..8579f4b --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/restobjects.md @@ -0,0 +1,825 @@ +--- +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` 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| +| `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.22.2/restprocessingpayments.md b/restapi_versioned_docs/version-REST API 2.22.2/restprocessingpayments.md new file mode 100644 index 0000000..91e60f2 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/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.22.2/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.22.2/restreleasenotes.md new file mode 100644 index 0000000..dd25f6b --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/restreleasenotes.md @@ -0,0 +1,107 @@ +--- +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.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: + +![SaleWithGetTrxStatusExample](/img/RestAPIexample.png) + +## 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.22.2/restsandbox.md b/restapi_versioned_docs/version-REST API 2.22.2/restsandbox.md new file mode 100644 index 0000000..0ec32b7 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.2/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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.22.3/assets/postmanCollection.png b/restapi_versioned_docs/version-REST API 2.22.3/assets/postmanCollection.png new file mode 100644 index 0000000..ec43e6e Binary files /dev/null and b/restapi_versioned_docs/version-REST API 2.22.3/assets/postmanCollection.png differ diff --git a/restapi_versioned_docs/version-REST API 2.22.3/restdownloads.md b/restapi_versioned_docs/version-REST API 2.22.3/restdownloads.md new file mode 100644 index 0000000..653b02c --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/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.22.3/restendpoints.md b/restapi_versioned_docs/version-REST API 2.22.3/restendpoints.md new file mode 100644 index 0000000..163cdf3 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/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. + +![getTrxStatusEndpoint](/img/getTransactionStatusEndpoint.drawio.png) + +**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.22.3/restintroduction.md b/restapi_versioned_docs/version-REST API 2.22.3/restintroduction.md new file mode 100644 index 0000000..5252785 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/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**. + + + + +![Sandbox logo](/img/RestApiDiagram) + + diff --git a/restapi_versioned_docs/version-REST API 2.22.3/restobjects.md b/restapi_versioned_docs/version-REST API 2.22.3/restobjects.md new file mode 100644 index 0000000..8579f4b --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/restobjects.md @@ -0,0 +1,825 @@ +--- +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` 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| +| `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.22.3/restprocessingpayments.md b/restapi_versioned_docs/version-REST API 2.22.3/restprocessingpayments.md new file mode 100644 index 0000000..91e60f2 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/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.22.3/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.22.3/restreleasenotes.md new file mode 100644 index 0000000..3774764 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/restreleasenotes.md @@ -0,0 +1,112 @@ +--- +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.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: + +![SaleWithGetTrxStatusExample](/img/RestAPIexample.png) + +## 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.22.3/restsandbox.md b/restapi_versioned_docs/version-REST API 2.22.3/restsandbox.md new file mode 100644 index 0000000..0ec32b7 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.3/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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.22.4/assets/postmanCollection.png b/restapi_versioned_docs/version-REST API 2.22.4/assets/postmanCollection.png new file mode 100644 index 0000000..ec43e6e Binary files /dev/null and b/restapi_versioned_docs/version-REST API 2.22.4/assets/postmanCollection.png differ diff --git a/restapi_versioned_docs/version-REST API 2.22.4/restdownloads.md b/restapi_versioned_docs/version-REST API 2.22.4/restdownloads.md new file mode 100644 index 0000000..653b02c --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/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.22.4/restendpoints.md b/restapi_versioned_docs/version-REST API 2.22.4/restendpoints.md new file mode 100644 index 0000000..163cdf3 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/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. + +![getTrxStatusEndpoint](/img/getTransactionStatusEndpoint.drawio.png) + +**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.22.4/restintroduction.md b/restapi_versioned_docs/version-REST API 2.22.4/restintroduction.md new file mode 100644 index 0000000..5252785 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/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**. + + + + +![Sandbox logo](/img/RestApiDiagram) + + diff --git a/restapi_versioned_docs/version-REST API 2.22.4/restobjects.md b/restapi_versioned_docs/version-REST API 2.22.4/restobjects.md new file mode 100644 index 0000000..8579f4b --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/restobjects.md @@ -0,0 +1,825 @@ +--- +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` 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| +| `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.22.4/restprocessingpayments.md b/restapi_versioned_docs/version-REST API 2.22.4/restprocessingpayments.md new file mode 100644 index 0000000..91e60f2 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/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.22.4/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.22.4/restreleasenotes.md new file mode 100644 index 0000000..9651679 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/restreleasenotes.md @@ -0,0 +1,117 @@ +--- +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.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: + +![SaleWithGetTrxStatusExample](/img/RestAPIexample.png) + +## 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.22.4/restsandbox.md b/restapi_versioned_docs/version-REST API 2.22.4/restsandbox.md new file mode 100644 index 0000000..0ec32b7 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.22.4/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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.23.0/assets/postmanCollection.png b/restapi_versioned_docs/version-REST API 2.23.0/assets/postmanCollection.png new file mode 100644 index 0000000..ec43e6e Binary files /dev/null and b/restapi_versioned_docs/version-REST API 2.23.0/assets/postmanCollection.png differ diff --git a/restapi_versioned_docs/version-REST API 2.23.0/restdownloads.md b/restapi_versioned_docs/version-REST API 2.23.0/restdownloads.md new file mode 100644 index 0000000..653b02c --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/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.0/restendpoints.md b/restapi_versioned_docs/version-REST API 2.23.0/restendpoints.md new file mode 100644 index 0000000..163cdf3 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/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. + +![getTrxStatusEndpoint](/img/getTransactionStatusEndpoint.drawio.png) + +**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.0/restintroduction.md b/restapi_versioned_docs/version-REST API 2.23.0/restintroduction.md new file mode 100644 index 0000000..5252785 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/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**. + + + + +![Sandbox logo](/img/RestApiDiagram) + + diff --git a/restapi_versioned_docs/version-REST API 2.23.0/restobjects.md b/restapi_versioned_docs/version-REST API 2.23.0/restobjects.md new file mode 100644 index 0000000..8579f4b --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/restobjects.md @@ -0,0 +1,825 @@ +--- +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` 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| +| `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.0/restprocessingpayments.md b/restapi_versioned_docs/version-REST API 2.23.0/restprocessingpayments.md new file mode 100644 index 0000000..91e60f2 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/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.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.23.0/restreleasenotes.md new file mode 100644 index 0000000..01faf55 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/restreleasenotes.md @@ -0,0 +1,122 @@ +--- +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.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: + +![SaleWithGetTrxStatusExample](/img/RestAPIexample.png) + +## 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.0/restsandbox.md b/restapi_versioned_docs/version-REST API 2.23.0/restsandbox.md new file mode 100644 index 0000000..0ec32b7 --- /dev/null +++ b/restapi_versioned_docs/version-REST API 2.23.0/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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file 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. + +![getTrxStatusEndpoint](/img/getTransactionStatusEndpoint.drawio.png) + +**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**. + + + + +![Sandbox logo](/img/RestApiDiagram) + + 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: + +![SaleWithGetTrxStatusExample](/img/RestAPIexample.png) + +## 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: + +![Sandbox logo](/img/cloudpos.png) + +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. + +![Sandbox logo](/img/cloudpos2.png) + +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. + +![Sandbox logo](/img/cloudpos3.png) + +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. + +![Sandbox logo](/img/cloudpos4.png) + +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. + +![Sandbox logo](/img/cloudpos5.png) \ No newline at end of file diff --git a/restapi_versioned_docs/version-REST API 2.6.0/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.6.0/restreleasenotes.md index 2cb989c..619694d 100644 --- a/restapi_versioned_docs/version-REST API 2.6.0/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.6.0/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.6.0 diff --git a/restapi_versioned_docs/version-REST API 2.7.1/restreleasenotes.md b/restapi_versioned_docs/version-REST API 2.7.1/restreleasenotes.md index 7b20aa7..c0d23bb 100644 --- a/restapi_versioned_docs/version-REST API 2.7.1/restreleasenotes.md +++ b/restapi_versioned_docs/version-REST API 2.7.1/restreleasenotes.md @@ -6,7 +6,7 @@ id: restreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 2.7.1 diff --git a/restapi_versioned_sidebars/version-REST API 2.22.2-sidebars.json b/restapi_versioned_sidebars/version-REST API 2.22.2-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/restapi_versioned_sidebars/version-REST API 2.22.2-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/restapi_versioned_sidebars/version-REST API 2.22.3-sidebars.json b/restapi_versioned_sidebars/version-REST API 2.22.3-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/restapi_versioned_sidebars/version-REST API 2.22.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/restapi_versioned_sidebars/version-REST API 2.22.4-sidebars.json b/restapi_versioned_sidebars/version-REST API 2.22.4-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/restapi_versioned_sidebars/version-REST API 2.22.4-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/restapi_versioned_sidebars/version-REST API 2.23.0-sidebars.json b/restapi_versioned_sidebars/version-REST API 2.23.0-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/restapi_versioned_sidebars/version-REST API 2.23.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} 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 430ff18..cd00d71 100644 --- a/restapi_versions.json +++ b/restapi_versions.json @@ -1,4 +1,9 @@ [ + "REST API 2.23.1", + "REST API 2.23.0", + "REST API 2.22.4", + "REST API 2.22.3", + "REST API 2.22.2", "REST API 2.20.0", "REST API 2.17.0", "REST API 2.15.0", diff --git a/src/pages/cpdocs.js b/src/pages/cpdocs.js index 297c73e..3eb8d3a 100644 --- a/src/pages/cpdocs.js +++ b/src/pages/cpdocs.js @@ -267,7 +267,7 @@ function Standalone() {

Handpoint offers a basic standalone application allowing your merchants to take payments without being connected to a point of sale software. When the card reader is used in standalone mode, the merchant can simply type in an amount and start processing payments. - The Handpoint standalone application offers a full set of functionalities, from powerful analytics, to end-of-day reports and manual card entry for over the phone transactions.

+ The Handpoint standalone application offers a full set of functionalities, from powerful analytics, to end-of-day reports and MoTo (Mail Order Telephone Order).

standalone terminal
@@ -372,8 +372,7 @@ function TableTerminals() {
+ alt="">
@@ -653,9 +652,6 @@ function TableTerminals() {

- - -

@@ -692,8 +688,26 @@ function TableTerminals() {
- - +

+
+
+
+
+
+

+ PAX A8900 (Full Touch Screen) +

+
+ + +
+
+
+
+
+
@@ -1329,11 +1343,11 @@ function HighLevelFeatures() {
-

Manual Card Entry / MOTO

+

MOTO

- MOTO (Mail Order / Telephone Order) also called manual card entry is a type of transaction used by merchants to get services paid via telephone, mail, fax, or internet communication. + MOTO (Mail Order / Telephone Order) is a type of transaction used by merchants to get services paid 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.

diff --git a/windows/windowsreleasenotes.md b/windows/windowsreleasenotes.md index e3682fc..f29447f 100644 --- a/windows/windowsreleasenotes.md +++ b/windows/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/windows_versioned_docs/version-Windows SDK 3.2.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 3.2.0/windowsreleasenotes.md index e97a634..a497414 100644 --- a/windows_versioned_docs/version-Windows SDK 3.2.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 3.2.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 3.2.0 diff --git a/windows_versioned_docs/version-Windows SDK 3.2.4/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 3.2.4/windowsreleasenotes.md index 2ad3a8e..632160e 100644 --- a/windows_versioned_docs/version-Windows SDK 3.2.4/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 3.2.4/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 3.2.4 diff --git a/windows_versioned_docs/version-Windows SDK 3.2.5/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 3.2.5/windowsreleasenotes.md index 7a7605b..6a1342c 100644 --- a/windows_versioned_docs/version-Windows SDK 3.2.5/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 3.2.5/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/windows_versioned_docs/version-Windows SDK 3.3.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 3.3.0/windowsreleasenotes.md index 77c54d5..e73b432 100644 --- a/windows_versioned_docs/version-Windows SDK 3.3.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 3.3.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 3.3.0 diff --git a/windows_versioned_docs/version-Windows SDK 3.4.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 3.4.0/windowsreleasenotes.md index deaa568..71ce608 100644 --- a/windows_versioned_docs/version-Windows SDK 3.4.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 3.4.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/windows_versioned_docs/version-Windows SDK 4.0.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 4.0.0/windowsreleasenotes.md index c09f2df..66e480d 100644 --- a/windows_versioned_docs/version-Windows SDK 4.0.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 4.0.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 4.0.0 diff --git a/windows_versioned_docs/version-Windows SDK 4.1.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 4.1.0/windowsreleasenotes.md index 0d45728..a3156ca 100644 --- a/windows_versioned_docs/version-Windows SDK 4.1.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 4.1.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 4.1.0 diff --git a/windows_versioned_docs/version-Windows SDK 4.2.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 4.2.0/windowsreleasenotes.md index b84f0c9..82e6058 100644 --- a/windows_versioned_docs/version-Windows SDK 4.2.0/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 4.2.0/windowsreleasenotes.md @@ -6,7 +6,7 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: diff --git a/windows_versioned_docs/version-Windows SDK 4.3.1/windowsobjects.md b/windows_versioned_docs/version-Windows SDK 4.3.1/windowsobjects.md index f4e3ed2..3597a1a 100644 --- a/windows_versioned_docs/version-Windows SDK 4.3.1/windowsobjects.md +++ b/windows_versioned_docs/version-Windows SDK 4.3.1/windowsobjects.md @@ -351,7 +351,7 @@ A class containing optional transaction parameters now supported by the device. | ----------- | ----------- | |`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 amount 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. Example: "03" or "24".| |`CustomerReference`
*String*|**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 36 characters and received back when the transaction has been processed. Example: "C.nr. 212311".| -|`tokenize`
*Boolean*| Used to enable tokenization in the payments flow. See [Android SDK 7.1009.5](/android/androidreleasenotes#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature.| +|`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.| |`DuplicateCheck`
*String*| 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 DuplicateCheck functionality is available for the following transactions:** Sale, Sale and Tokenize, Sale Reversal, Refund and Refund Reversal.


The Duplicate Check service is **enabled by default**, if you want to disable it, you must use the `String` "0", for example: ```options.Add(XmlTag.DuplicateCheck.Tag(), "0");```| | `Metadata1`
*String*|**String Metadata1 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata1.Tag(), "Data 1");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| | `Metadata2`
*String*|**String Metadata2 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata2.Tag(), "Data 2");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| diff --git a/windows_versioned_docs/version-Windows SDK 4.3.1/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 4.3.1/windowsreleasenotes.md index 8352047..1d6dfcc 100644 --- a/windows_versioned_docs/version-Windows SDK 4.3.1/windowsreleasenotes.md +++ b/windows_versioned_docs/version-Windows SDK 4.3.1/windowsreleasenotes.md @@ -6,12 +6,12 @@ id: windowsreleasenotes # Release Notes :::tip -Do not miss any news from Handpoint releases. [Subscribe](https://handpoint.us6.list-manage.com/subscribe?u=4d9dff9e7edb7e57a67a7b252&id=0a2179241e) to our Handpoint Newsletter! +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! ::: ## 4.3.1 **Features:** -A new `tokenize` parameter is available under [Optional Transaction Parameters](windowsobjects.md). See [Android SDK 7.1009.5](/android/androidreleasenotes#7.1009.5) and [Tokenized Payments Operations](/android/androidtransactions#cloudTokenizedPaymentsOperations) for detailed information on how to use this feature. +A new `tokenize` parameter is available under [Optional Transaction Parameters](windowsobjects.md). 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. ## 4.2.0 **Features:** diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowsapioverview.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsapioverview.md new file mode 100644 index 0000000..6283367 --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsapioverview.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 3 +id: windowsapioverview +--- + +# 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/windows_versioned_docs/version-Windows SDK 4.4.0/windowsdevicemanagement.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsdevicemanagement.md new file mode 100644 index 0000000..99af86d --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsdevicemanagement.md @@ -0,0 +1,361 @@ +--- +sidebar_position: 6 +id: windowsdevicemanagement +--- + +# Terminal Management + +## Connect + +`Connect` Method + +Configures the device as the preferred device and tries to connect to it. Everytime a new connection is started the SDK will make 3 attempts to re-establish the connection. If those attempts fail, the connection is considered dead. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used.| + + +**Code example** + +```csharp +//Connect to a CLOUD device (PAX/Telpo) +Device device = new Device("CloudDevice", "9822032398-PAXA920", "", ConnectionMethod.Cloud); +// The address is the composition of the serial number and model ot the target device. +//Example for a PAX A920 device: serial_number - model -> 9822032398-PAXA920 +api.Connect(device); + +//Connect to a BLUETOOTH device (HiLite) +Device device = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); +api.Connect(device); +``` + +#### Events invoked + +**[*ConnectionStatusChanged*](windowsevents.md#7)** + +Each time the card reader state changes (ex : going from Connected to Disconnected) the **[*ConnectionStatusChanged*](windowsevents.md#7)** event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successful.| + + +## Disconnect + +`Disconnect` Method + +Disconnect will stop the active connection (and reconnection process). Please note that the method does NOT ignore the current state of the payment terminal. This means that if a disconnect is attempted during a transaction it will not be successful and the method will return `false`. If a transaction is not in progress, the disconnect will take 1-3 seconds to successfully finish and will then return `true`. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Disconnect from current device +api.Disconnect(); +``` + +#### Events invoked + +**[*ConnectionStatusChanged*](windowsevents.md#7)** + +Each time the card reader state changes (ex : going from Connected to Disconnected) the **[*ConnectionStatusChanged*](windowsevents.md#7)** event is called. It causes the connection manager to invoke this event with the appropriate information. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was succesful| + +## Set shared secret + +`SetSharedSecret` Method + +Validates your application for this session, thus enabling financial transactions. + +#### Parameters +| Parameter | Notes | +| ----------- | ----------- | +| `sharedSecret` Required
*String* | The shared secret is a an authentication key provided by Handpoint, it is unique per merchant (not per terminal).| +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Sets the shared secret +api.SetSharedSecret("0102030405060708091011121314151617181920212223242526272829303132"); +``` + +#### Events invoked + +**None** + +No events invoked. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to the payment terminal.| + + + +## Set logging level + +`SetLogLevel` Method + +Sets the log level (info, debug etc.) for both the payment terminal and the API. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `level` Required
[*LogLevel*](windowsobjects.md#9) | The desired log level. Possible values are `LogLevel.None`, `LogLevel.Info`, `LogLevel.Full`, `LogLevel.Debug`.| +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Sets the log level to info +api.SetLogLevel(LogLevel.info); +``` + +#### Events invoked + +**None** + +No events are invoked. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to the payment terminal.| + + +## Request device logs + +`GetDeviceLogs` Method + +Fetches the logs from the payment terminal and reports them to the [DeviceLogsReady](windowsevents.md#WinDeviceLogsReady) event. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Downloads logs from device +api.GetDeviceLogs(); +``` + +#### Events invoked + +**[*DeviceLogsReady*](windowsevents.md#WinDeviceLogsReady)** + +Invoked when the SDK has finished downloading logs from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to the payment terminal.| + + +## Request pending transaction results + +`GetPendingTransaction` Method + +In the case of a communication failure between the device and the SDK a TransactionResult might have not been delivered to the API. This function fetches a pending TransactionResult (which contains receipts) from the payment terminal, if any. If no TransactionResult was pending a result will be delivered containing default fields. In order to receive only valid TransactionResults this function should only be called when PendingTransactionResult event is invoked or when HapiManager.IsTransactionResultPending() is true. To receive events when a TransactionResult is pending on the device please add the Events.PendingResults listener. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Fetches a pending TransactionResult from a device +api.GetPendingTransaction(); +``` + +#### Events invoked + +**[*TransactionResultReady*](windowsevents.md#11)** + +Invoked when the SDK has finished fetching a TransactionResult from the payment terminal. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to the payment terminal.| + + +## Update device + +`Update` Method + +The update operation checks for available software or configuration update. If an update is pending it will be downloaded and installed by the payment terminal. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | This parameter specifies to the sdk which payment terminal should be used. If none is supplied the system will attempt to use a default device, if any.| + +**Code example** + +```csharp +//Check for card reader update +api.Update(); +``` + +#### Events invoked + +**None** + +Information about this process should be available at the device's screen. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the operation was successfully sent to the payment terminal.| + + +## List Devices (search) + +`ListDevices` Method + +Starts the search for payment terminals to connect to. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `method` Required
[*ConnectionMethod*](windowsobjects.md#12) | The connection type to the payment terminal (Bluetooth or Cloud)| + +**Code example** + +```csharp +//Search for Bluetooth devices +api.ListDevices(ConnectionMethod.BLUETOOTH); + +//Search for Cloud devices +api.ListDevices(ConnectionMethod.CLOUD); +``` + +#### Events invoked + +**[*deviceDiscoveryFinished*](windowsevents.md#13)** + +Returns a list of available payment terminals. + +## Start monitoring connections + +`StartMonitoringConnections` Method + +Starts a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with USB. In the case of USB the service will only disconnect from the device and when it notices that it has been plugged in again it will connect to it. + +**Code example** + +```csharp +//Starts the connection monitoring service +//app starts it's life-time +api.StartMonitoringConnections(); +... +//app ends its life-time +api.StopMonitoringConnections(); +``` + +#### Events invoked + +**[*ConnectionStatusChanged*](windowsevents.md#7)** + +Invoked when the status of the connection with the payment terminal changes. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **None**| No information is returned.| + + + +## Stop monitoring connections + +`StopMonitoringConnections` Method + +Stops a connection monitoring service. The service listens to events sent by the operating system about the connected hardware. If the service notices that a previously connected device suddenly disconnects on the hardware layer it attempts to reconnect to that particular device. Since this is a service it is necessary that the service is turned off before the application ends its life-time. This means that, if the service was running, stopMonitoringConnections() has to be called before the application is exited completely. Note that the service currently only works with USB. In the case of USB the service will only disconnect from the device and when it notices that it has been plugged in again it will connect to it. + +**Code example** + +```csharp +//Starts the connection monitoring service +//app starts it's life-time +api.StartMonitoringConnections(); +... +//app ends its life-time +api.StopMonitoringConnections(); +``` + +#### Events invoked + +**[*ConnectionStatusChanged*](windowsevents.md#7)** + +Invoked when the status of the connection with the payment terminal changes. + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| **None**| No information is returned.| + +## Get Transaction Status + +`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](windowsobjects.md#OperationStartResult) object. + +The main [*FinancialStatus*](windowsobjects.md#25) 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. +- 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. + +**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 [OperationStartResult](windowsobjects.md#OperationStartResult) object.| + +**Code example** + +```csharp +//Gets the current status of a transaction +this.Hapi.GetTransactionStatus("00000000-0000-0000-0000-000000000000"); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [TransactionResult](windowsobjects.md#14)| An object holding information about the result of a transaction.| \ No newline at end of file diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowsevents.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsevents.md new file mode 100644 index 0000000..8d62ada --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsevents.md @@ -0,0 +1,238 @@ +--- +sidebar_position: 8 +id: windowsevents +--- + +# Events Listeners + +## Transaction Result Recovery over CLOUD connection + +`CloudTransactionResultRecovery` Method + +The terminal has a transaction recovery loop to automatically send back the pending [Transaction Result](windowsobjects.md#14) to the point of sale 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 point of sale 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.The [Transaction Result](windowsobjects.md#14) received through the transaction recovery loop will have the recoveredTransaction field set to true. + +**Important information: The point of sale must be successfully connected to a terminal in order to receive the pending transactions.** + +**Returns:** + +**[*Transaction Result Ready Event*](windowsevents.md#11)** + +Event containing the pending [Transaction Result](windowsobjects.md#14). + +## Device discovery finished{#13} + +`deviceDiscoveryFinished` + +The deviceDiscoveryFinished event gets called when the payment terminal search has finished, it returns a list of devices. + +##### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a list of connectable devices +List myListOfDevices = new List(); +public void deviceDiscoveryFinished(List devices) +{ + foreach(Device device in devices) + { + myListOfDevices.Add(device); + } +} +``` + + +## Signature required{#5} + +`SignatureRequired` Method + +The SignatureRequired event gets called when the card issuer requires a signature. This event is only required for an Hilite integration, PAX and Telpo terminals automatically prompt for signature capture on the payment terminal. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `request` Required
[*SignatureRequest*](windowsobjects.md#17) | Holds the signature request object.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a SignatureRequest from the SDK. +public void SignatureRequired(SignatureRequest signatureRequest, Device device) +{ + //You might want to print out the receipt or ask the customer to sign the receipt on your device + DisplayReceiptInUI(signatureRequest.MerchantReceipt) + //If you accept the signature + api.SignatureResult(true); +} +``` + +## End of transaction{#6} + +`EndOfTransaction` Method + +The EndOfTransaction event gets called at the end of each transaction and has two parameters, result and device. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*TransactionResult*](windowsobjects.md#14) | Holds the result and receipts for the transaction.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a TransactionResult from the SDK. +public void EndOfTransaction(TransactionResult transactionResult, Device device) +{ + //You might want to display this information in the UI + postTransactionResultToUI(transactionResult); +} +``` + +## Connection status changed{#7} + +`ConnectionStatusChanged` + +The ConnectionStatusChanged event gets called when the state of a payment terminal connection changes. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `status` Required
[*ConnectionStatus*](windowsobjects.md#18) | An enum containing the status code for the connection.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a new ConnectionStatus from the SDK +public void ConnectionStatusChanged(ConnectionStatus connectionStatus, Device device) +{ + //You might want to display this information in the UI + postNewStatusToUI(connectionStatus); +} +``` + +## Current transaction status{#4} + +`CurrentTransactionStatus` Method + +The currentTransactionStatus event gets called when the state of an ongoing transaction changes. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `statusInfo` Required
[*StatusInfo*](windowsobjects.md#statusInfo) | An object containing information about the current transaction.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a transaction status from the SDK. +public void currentTransactionStatus(StatusInfo statusInfo, Device device) +{ + //You might want to display some of this information in the UI + DisplayTransactionStatusInUI(statusInfo) +} +``` + +## Message logged + +`OnMessageLogged` Method + +The OnMessageLogged event gets called for each and every message logged by the SDK. This function is only intended for debugging. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `logLevel` Required
[*LogLevel*](windowsobjects.md#9) | An enum containing the log level.| +| `message` Required
*String* | A String containing the current log message.| + +**Code example** + +```csharp +//Receiving a log from the SDK +public void OnMessageLogged(LogLevel logLevel, String message) +{ + //You do not want to display this information in the UI + Debug.WriteLine(message); +} +``` + +## Device Logs ready{#WinDeviceLogsReady} + +`DeviceLogsReady` Method + +The DeviceLogsReady event gets called when the payment terminal logs are ready to be delivered (in response to a request to getDeviceLogs()). This Event is useful if case of a communication error between the payment terminal and the API (e.g : Bluetooth communication lost). After reconnecting, you can then fetch the card reader logs to the API. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `logs` Required
*String* | String containing the current log.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +//Receiving a log from the device +public void DeviceLogsReady(string logs, Device device) +{ + //You might want to save this information + WriteLogsToDisk(logs); +} +``` + +## Pending transaction result + +`PendingTransactionResult` Method + +In case of a communication failure between the payment terminal and your application a TransactionResult might have not been delivered to the SDK. This event is invoked when the device has a pending TransactionResult. This event might be invoked when reconnecting to a device after a communication failure during a transaction. This event will not be called if HapiManager.Settings.AutoRecoverTransactionResult is set to true. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +@Override +public void PendingTransactionResult(Device device){ + //Here you might want to call api.GetPendingTransaction(); to receive the TransactionResult +} +``` + +## Transaction result ready{#11} + +`TransactionResultReady` Method + +In case of a communication failure between the device and your application a TransactionResult might have not been delivered to the SDK. This event will be invoked after using hapi.GetPendingTransaction();. When there is no pending transaction the TransactionResult will contain default/error fields and no receipts. This event is called if HapiManager.Settings.AutoRecoverTransactionResult is set to true. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `result` Required
[*TransactionResult*](windowsobjects.md#14) | Holds the results for the transaction.| +| `device` Required
[*Device*](windowsobjects.md#2) | The payment terminal invoking the event.| + +**Code example** + +```csharp +@Override +public void TransactionResultReady(TransactionResult transactionResult, Device device){ + //Here you might want to do stuff to the transactionResult +} +``` diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowseventsubscribers.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowseventsubscribers.md new file mode 100644 index 0000000..4f361cf --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowseventsubscribers.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 7 +id: windowseventssubscribers +--- + + +# Events Subscribers + +## Register events delegate + +`RegisterEventsDelegate` Method + +Registers a delegate for the SDK events. The method getAsyncInterface in HapiFactory executes internally this subscription. + +##### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `listener` Required
*Object* | Any Object implementing one or more of the available delegate interfaces| + +**Code example** + +```csharp +public class ObjectHelper : Events.Required, Events.Status, Events.Log { + ... + private void RegisterEventHandler() { + // 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** + +```csharp +public class ObjectHelper : Events.Required, Events.Status, Events.Log { + ... + private void Unsubscribe() { + // Stop receiving events + this.api.UnregisterEventsDelegate(this); + ... +} +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `True` if the new delegate was removedded successfully.| + + diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintegrationguide.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintegrationguide.md new file mode 100644 index 0000000..1ff930d --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintegrationguide.md @@ -0,0 +1,2002 @@ +--- +sidebar_position: 4 +id: windowsintegrationguide +--- + +# Integration Guides + +**The SDK supports the following connection methods:** + +1. **[Cloud (PAX/Telpo)](#WinPaxIntegration)** +2. **[Bluetooth (HiLite)](#WinHiLiteIntegration)** + +## Cloud (PAX/Telpo) {#WinPaxIntegration} + +### Introduction + +### Let's start programming! + +**1. Create a C# class** + +Create a new C# class called MyClass and include com.handpoint.api as a dependency : + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass + { + } +} +``` + +**2. Initialize the API** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass + { + Hapi api; + + public MyClass() + { + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-is-my-api-key-provided-by-Handpoint"; + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret, apikey)); + // 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 a free field. + // The Api key is a unique key per merchant used to authenticate the terminal against the Cloud. + // You should replace the API key with the one sent by the Handpoint support team. + } + } +} +``` + +**3. Implement the mandatory Events(Events.Required) and per recommendation Status events (Events.Status)** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + + public MyClass() + { + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-is-my-api-key-provided-by-Handpoint" + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret, apikey)); + } + + public void DeviceDiscoveryFinished(List devices) + { + // here you get a list of payment terminals associated with the api key. + } + + 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. + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + // The ConnectionStatus object holds details about the status regarding the connection to the target device. + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + // The StatusInfo object holds details about the status and step taken during the transaction. + } + + public void SignatureRequired(SignatureRequest request, Device device) + { + // Ignore for a PAX/Telpo integration. The complete signature capture process + // is already handled in the sdk, a dialog will prompt the user for a signature if required. + // If a signature was entered, it should be printed on the receipts. + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + // Ignore, legacy event, will be deleted in future version. + } + } +} +``` + +**4. Add a method to list the terminals of your merchant and connect to one of them** +Ensure that the card reader and PC are correctly paired via Cloud connection. + +```csharp +public void DiscoverDevices() +{ + // This triggers the search for all the cloud devices related to your Api Key. + api.SearchDevices(ConnectionMethod.CLOUD); +} + +public void DeviceDiscoveryFinished(List devices) +{ + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("CloudDevice")) + // Put the name of your device + + { + this.myDevice = device; + //We'll remember the device for this session, it is nice if you would do that too + api.Connect(this.myDevice); + //Connection to the device is handled automatically by the api + } + } + } +} +``` + +**5. Add a method to connect directly to the payment terminal** +Instead of discovering terminals you can also connect directly to one of them: + +```csharp +public void DirectConnect() +{ + Device device = new Device("CloudDevice", "0821032395-PAXA920", "", ConnectionMethod.CLOUD); + // new Device("name", "address", "port (optional)", ConnectionMethod); + // The address always has to be written in UPPER CASE + // It is the composition of the serial number and model ot the payment terminal. + // Example for a PAX A920 device: serial_number - model -> 0821032395-PAXA920 + api.Connect(device); +} +``` + +**6. Add a method to take payments** + +```csharp +public OperationStartResult Pay() +{ + return api.Sale(new BigInteger(1000), Currency.EUR); + // Let´s start our first transaction for 10 euros + // The amount should always be in the minor unit of the currency +} +``` + +**7. Add a method to get the transactions status** + +This functionality is only available for SmartPos devices (PAX). + +```csharp +public TransactionResult GetTransactionStatus(String transactionReference) +{ + return api.GetTransactionStatus(transactionReference); +} +``` + +**8. Add a method to disconnect from the card reader** + +```csharp +public void Disconnect() +{ + api.Disconnect(); +} +``` + +**9. Eventually, MyClass.cs must look like this after implementing all the necessary methods :** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + + public MyClass(Form1 form1) + { + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-is-my-api-key-provided-by-Handpoint" + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret, apikey)); + } + + public void DiscoverDevices() + { + api.SearchDevices(ConnectionMethod.CLOUD); + } + + public void DeviceDiscoveryFinished(List devices) + { + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("CloudDevice")) + + { + this.myDevice = device; + api.Connect(this.myDevice); + } + } + } + } + + public void DirectConnect() + { + Device device = new Device("CloudDevice", "0821032395-PAXA920", "", ConnectionMethod.CLOUD); + api.Connect(device); + } + + public OperationStartResult Pay() + { + return api.Sale(new BigInteger(1000), Currency.EUR); + // Let´s start our first transaction for 10 euros + // The amount should always be in the minor unit of the currency + } + + public TransactionResult GetTransactionStatus(String transactionReference) + { + return api.GetTransactionStatus(transactionReference); + } + + public void Disconnect() + { + api.Disconnect(); + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + Console.WriteLine("*** ConnectionStatus *** " + status); + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); + } + + public void EndOfTransaction(TransactionResult result, Device device) + { + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + //Ignore + } + + public void SignatureRequired(SignatureRequest request, Device device) + { + //Ignore + } + } +} +``` + +### Let's create a User Interface! + +**1. Create buttons and labels** +- Go to your user interface (usually Form1.cs[Design]) +- Select View > Toolbox +- In the toolbox, under “Common Controls” drag and drop 4 button items to the user interface +- Select "button1" > Right-Click > Properties +- Change the attribute "Name" from "button1" to "PayButton" +- Change the attribute "text" from "button1" to "Pay Now" +- Change the attribute "Name" from "button2" to "GetTransactionStatusButton" +- Change the attribute "text" from "button2" to "Get Transaction Status" +- Change the attribute "Name" from "button3" to "ConnectButton" +- Change the attribute "text" from "button3" to "Connect To Card reader" +- Change the attribute "Name" from "button4" to "DisconnectButton" +- Change the attribute "text" from "button4" to "Disconnect From Card Reader" +- Select View > Toolbox > Common Controls > Label +- Change the attribute "Name" from "label1" to "ConnectionLabel" +- Change the attribute "text" from "label1" to "Disconnected" +- Change the attribute "backColor" from "label1" to "Red" + +**2. Create WebBrowsers** +Now that we have our 3 buttons, let´s create two webBrowsers items to display the merchant receipt as well as the cardholder´s receipt at the end of the transaction. + +- Select View > Toolbox > Common Controls > WebBrowser +- Drag and drop two web browsers to the user interface +- Select View > Toolbox > Common Controls > Label +- Drag and drop two labels to the user interface in order to identify the webBrowser items +- Change the attribute "Name" from the left webBrowser to "MerchantReceiptBrowser" +- Change the attribute "Name" from the right webBrowser to "CardholderReceiptBrowser" +- Change the attribute "Name" from "label2" to "MerchantReceiptLabel" +- Change the attribute "text" from "label2" to "Merchant Receipt :" +- Change the attribute "Name" from "label3" to "CardholderReceiptLabel" +- Change the attribute "text" from "label3" to "Cardholder Receipt :" + +### Let's link our user interface with methods! + +**1. Referencing the user interface(Form1.cs) in MyClass** + +In MyClass.cs, create an instance of Form1 called UIClass and initialize it. Instantiate MyClass and add form1 as a parameter for the Class. + +```csharp +class MyClass : Events.Required, Events.Status +{ + Hapi api; + Device myDevice; + private Form1 uIClass; + + public MyClass(Form1 form1) + { + uIClass = form1; + InitApi(); + } + + [...] +} +``` + +**2. Referencing Myclass in Form1.cs and link methods to the user interface** +Go to Form1.cs[Design] and double click on the button "Pay Now". By Double Clicking on it you created a method called PayButton_Click. Do the same with the button "Get Transaction Status". Create a new instance of MyClass called "my" in Form1.cs then, inside the new method PayButton_Click call the Pay() method from MyClass. + +```csharp +using System; +using System.Drawing; +using System.Windows.Forms; + +namespace GettingStartedApp +{ + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + + private void GetTransactionStatusButton_Click(object sender, EventArgs e) + { + //Use a transactionReference from your own transactions. 91ff1ed2-beee-44ca-96f9-9acec74dc659 is a test transactionReference + my.GetTransactionStatus("91ff1ed2-beee-44ca-96f9-9acec74dc659"); + } + } +} +``` + +Go back to Form1.cs[Design] and double click on each of the other buttons to automatically generate an OnClick method in Form1.cs. Link each of the buttons to the correct methods in MyClass.cs. + +```csharp +using System; +using System.Drawing; +using System.Windows.Forms; + +namespace GettingStartedApp +{ + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + + private void GetTransactionStatusButton_Click(object sender, EventArgs e) + { + //Use a transactionReference from your own transactions. 91ff1ed2-beee-44ca-96f9-9acec74dc659 is a test transactionReference + my.GetTransactionStatus("91ff1ed2-beee-44ca-96f9-9acec74dc659"); + } + + private void ConnectButton_Click(object sender, EventArgs e) + { + //my.DiscoverDevices(); + my.DirectConnect(); + } + + private void DisconnectButton_Click(object sender, EventArgs e) + { + my.Disconnect(); + } + } +} +``` + +### Let´s notify the user when the app is connected and ready to send the transaction + +**1. Update the ConnectionLabel to notify the user of the connection status** +Get the connection status from the method **[*ConnectionStatusChanged*](#7)** in MyClass.cs. + +```csharp +public void ConnectionStatusChanged(ConnectionStatus status, Device device) +{ + Console.WriteLine("*** ConnectionStatus *** " + status); + if (status == ConnectionStatus.Connected) + { + uIClass.UpdateLabel(true); + } + else + { + uIClass.UpdateLabel(false); + } +} + +public void CurrentTransactionStatus(StatusInfo info, Device device) +{ + //Let also console log the status during the transaction + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); +} +``` + +**2. Create the UpdateLabel method in Form1.cs** + +```csharp +public delegate void UpdateConnectionLabel(bool Connected); +public void UpdateLabel(bool Connected) +{ + //Only need to check for one of the webbrowsers + if (ConnectionLabel.InvokeRequired) + { + UpdateConnectionLabel d = new UpdateConnectionLabel(UpdateLabel); + this.Invoke(d, new object[] { Connected }); + } + else + { + if (Connected) + { + ConnectionLabel.Text = "Connected"; + ConnectionLabel.BackColor = Color.Green; + } + else { + ConnectionLabel.Text = "Disconnected"; + ConnectionLabel.BackColor = Color.Red; + } + } +} +``` + +### Let´s display the receipts at the end of a transaction! + +**1. Fetch the cardholder's and merchant receipts from the method EndOfTransaction in MyClass** +At this point all the buttons are connected but we are still missing to display the receipts in the webBrowsers. First, let´s get the receipts from the method EndOfTransaction in myClass.cs. + +```csharp +public void EndOfTransaction(TransactionResult transactionResult, Device device) +{ + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + uIClass.DisplayReceipts(result.MerchantReceipt, result.CustomerReceipt); +} +``` + +**2. Create the DisplayReceipts method in Form1.cs** + +```csharp +public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); +public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) +{ + //Only need to check for one of the webbrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } +} +``` + +### Final Result! + +Here is how MyClass.cs and Form1.cs must eventually look like: + +**1. MyClass.cs :** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + private Form1 uIClass; + + public MyClass(Form1 form1) + { + uIClass = form1; + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-is-my-api-key-provided-by-Handpoint" + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret, apikey)); + } + + public void DiscoverDevices() + { + api.SearchDevices(ConnectionMethod.CLOUD); + } + + public void DirectConnect() + { + Device device = new Device("CloudDevice", "0821032398-PAXA920", "", ConnectionMethod.CLOUD); + api.Connect(device); + } + + public OperationStartResult Pay() + { + //A new sale operation will generate a transactionReference that can be used + //to check the status of the transaction (GetTransactionStatus) + return api.Sale(new BigInteger(1000), Currency.EUR); + } + + public TransactionResult GetTransactionStatus(String transactionReference) + { + return api.GetTransactionStatus(transactionReference); + } + + public void Disconnect() + { + api.Disconnect(); + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + Console.WriteLine("***ConnectionStatus*** " + status); + if (status == ConnectionStatus.Connected) + { + uIClass.UpdateLabel(true); + } + else + { + uIClass.UpdateLabel(false); + } + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + //Let's log also the status during the transaction + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); + } + + public void DeviceDiscoveryFinished(List devices) + { + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("CloudDevice")) + { + this.myDevice = device; + api.Connect(this.myDevice); + } + } + } + } + + public void EndOfTransaction(TransactionResult result, Device device) + { + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + uIClass.DisplayReceipts(result.MerchantReceipt, result.CustomerReceipt); + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + //Ignore + } + + public void SignatureRequired(SignatureRequest request, Device device) + { + //Ignore + } + } +} +``` + +**2. Form1.cs :** + +```csharp + using System; + using System.Drawing; + using System.Windows.Forms; + + namespace GettingStartedApp + { + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + + private void GetTransactionStatusButton_Click(object sender, EventArgs e) + { + //Use a transactionReference from your own transactions. 91ff1ed2-beee-44ca-96f9-9acec74dc659 is a test transactionReference + my.GetTransactionStatus("91ff1ed2-beee-44ca-96f9-9acec74dc659"); + } + + private void ConnectButton_Click(object sender, EventArgs e) + { + my.DirectConnect(); + } + + private void DisconnectButton_Click(object sender, EventArgs e) + { + my.Disconnect(); + } + + public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); + public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) + { + //Only need to check for one of the webbrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } + } + + public delegate void UpdateConnectionLabel(bool connected); + + public void UpdateLabel(bool Connected) + { + //Only need to check for one of the webbrowsers + if (ConnectionLabel.InvokeRequired) + { + UpdateConnectionLabel d = new UpdateConnectionLabel(UpdateLabel); + this.Invoke(d, new object[] { Connected }); + } + else + { + if (Connected) + { + ConnectionLabel.Text = "Connected"; + ConnectionLabel.BackColor = Color.Green; + } + else { + ConnectionLabel.Text = "Disconnected"; + ConnectionLabel.BackColor = Color.Red; + } + } + } + + } + } +``` + +### Let's run our program! + +Run the program by clicking the "play" button : + +1. Click on "Connect To Card Reader", this can take a little bit of time (10 sec max) due to the fact that we are looking for all the devices around before connecting to a specific one +2. Click "Pay Now" +3. Follow the instructions on the card reader +4. When the transaction is finished, the receipts should be displayed in the webBrowsers. +5. Click "Get Transaction Status", you will get the transaction Status from the used transactionReference +5. Click on "Disconnect From Card Reader" to stop the connection with the card reader + +## Bluetooth (HiLite) {#WinHiLiteIntegration} + +### Introduction + +This tutorial is guiding you through all the steps to create a basic payment application for Windows devices integrated with an HiLite 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. + +### How to implement a Sale Transaction + +The below flow chart shows the interaction between the SDK, the payment terminal and your application. The orange arrows represent methods (requests) that need to be invoked to communicate with the Handpoint SDK's. The dark arrows represent events that need to be integrated in your code in order to retrieve information from the SDK´s and the card reader. + +![Sandbox logo](/img/SaleTransaction.png) + +### How to implement a Sale Transaction with Recovery feature + +At some point, the connection between the SDK and the card reader can become unstable. For example, the Bluetooth connection can be cut in the middle of a sale transaction if the smartphone runs out of battery. If this happens, you need to have implemented the “transaction recovery feature” in order to get the receipts from the previous transaction and knowing if it was successful despite the connection problem. + +![Sandbox logo](/img/SaleTransactionRecovery.png) + +### Let's start programming! + +**1. Create a C# class** +Create a new C# class called MyClass and include com.handpoint.api as a dependency : + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass + { + } +} + +```` + +**2. Initialize the API** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass + { + Hapi api; + + public MyClass() + { + InitApi(); + } + + 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! + // The shared secret is a unique string shared between the card reader and your mobile application. + // It prevents other people to connect to your card reader. + // You should replace this default shared secret by the one sent by our support team. + } + } +} +``` + +**3. Implement the mandatory Events(Events.Required) and per recommendation Status events (Events.Status)** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + + public MyClass() + { + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret)); + } + + public void DeviceDiscoveryFinished(List devices) + { + // Here you get a list of Bluetooth payment terminals paired with your computer + } + + 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. + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + // The ConnectionStatus object holds details about the status regarding the connection to the target device. + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + // The StatusInfo object holds details about the status and step taken during the transaction. + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + + api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt. + // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + // Ignore, legacy event, will be deleted in future version. + } + } +} +``` + +**4. Add a method to discover surrounding devices and connect to the card reader** +Ensure that the card reader and PC are correctly paired via bluetooth. + +```csharp +public void DiscoverDevices() +{ + api.ListDevices(ConnectionMethod.BLUETOOTH); + // This triggers the search for all the bluetooth devices around. + // You can also search for USB and Serial as a connection method +} + +public void DeviceDiscoveryFinished(List devices) +{ + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("PP0513901435")) + // Put the name of your device, find it by doing C then up arrow on your card reader keypad + { + this.device = device; + //We'll remember the device for this session, it is nice if you would do that too + api.Connect(this.device); + //Connection to the device is handled automatically in the API + } + } + } +} +``` +**5. Add a method to connect directly to the card reader** +Instead of discovering the surrounding devices you can also directly connect to the card reader by implementing the following method: + +```csharp +public void DirectConnect() +{ + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + //new Device("name", "address", "port", ConnectionMethod); + //The address always has to be written in UPPER CASE + api.Connect(device); +} +``` + +**6. Add a method to take payments** + +```csharp +public bool Pay() +{ + return api.Sale(new BigInteger(1000), Currency.GBP); + // Let´s start our first payment of 10 pounds +} +``` + +**7. Add a method to disconnect from the card reader** + +```csharp +public void Disconnect() +{ + api.Disconnect(); +} +``` + +**8. Eventually, MyClass.cs must look like this after implementing all the necessary methods :** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + + public MyClass(Form1 form1) + { + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret)); + } + + public void DiscoverDevices() + { + api.SearchDevices(ConnectionMethod.BLUETOOTH); + } + + public void DeviceDiscoveryFinished(List devices) + { + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("PP0513901435")) + { + this.device = device; + api.Connect(this.device); + } + } + } + } + + public void DirectConnect() + { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + api.Connect(device); + } + + public bool Pay() + { + return api.Sale(new BigInteger(1000), Currency.GPB); + } + + public void Disconnect() + { + api.Disconnect(); + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + Console.WriteLine("*** ConnectionStatus *** " + status); + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + api.SignatureResult(true); + } + + public void EndOfTransaction(TransactionResult result, Device device) + { + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + //Ignore + } + } +} +``` + +### Let's create a User Interface! + +**1. Create buttons** +- Go to your user interface (usually Form1.cs[Design]) +- Select View > Toolbox +- In the toolbox, under “Common Controls” drag and drop 3 button items to the user interface +- Select "button1" > Right-Click > Properties +- Change the attribute "Name" from "button1" to "PayButton" +- Change the attribute "text" from "button1" to "Pay Now" +- Change the attribute "Name" from "button2" to "ConnectButton" +- Change the attribute "text" from "button2" to "Connect To Card reader" +- Change the attribute "Name" from "button3" to "DisconnectButton" +- Change the attribute "text" from "button3" to "Disconnect From Card Reader" +- Select View > Toolbox > Common Controls > Label +- Change the attribute "Name" from "label1" to "ConnectionLabel" +- Change the attribute "text" from "label1" to "Disconnected" +- Change the attribute "backColor" from "label1" to "Red" + +**2. Create WebBrowsers** + +Now that we have our 3 buttons, let´s create two webBrowsers items to display the merchant receipt as well as the cardholder´s receipt at the end of the transaction. + +- Select View > Toolbox > Common Controls > WebBrowser +- Drag and drop two web browsers to the user interface +- Select View > Toolbox > Common Controls > Label +- Drag and drop two labels to the user interface in order to identify the webBrowser items +- Change the attribute "Name" from the left webBrowser to "MerchantReceiptBrowser" +- Change the attribute "Name" from the right webBrowser to "CardholderReceiptBrowser" +- Change the attribute "Name" from "label2" to "MerchantReceiptLabel" +- Change the attribute "text" from "label2" to "Merchant Receipt :" +- Change the attribute "Name" from "label3" to "CardholderReceiptLabel" +- Change the attribute "text" from "label3" to "Cardholder Receipt :" + +### Let's link our user interface with methods! + +**1. Referencing the user interface(Form1.cs) in MyClass** + +In MyClass.cs, create an instance of Form1 called UIClass and initialize it. Instantiate MyClass and add form1 as a parameter for the Class. + +```csharp +class MyClass : Events.Required, Events.Status +{ + Hapi api; + Device myDevice; + private Form1 uIClass; + + public MyClass(Form1 form1) + { + uIClass = form1; + InitApi(); + } + + [...] +} +``` + +**2. Referencing Myclass in Form1.cs and link methods to the user interface** + +Go to Form1.cs[Design] and double click on the button "Pay Now". By Double Clicking on it you created a method called PayButton_Click. Create a new instance of MyClass called "my" in Form1.cs then, inside the new method PayButton_Click call the Pay() method from MyClass. + +```csharp +using System; +using System.Drawing; +using System.Windows.Forms; + +namespace GettingStartedApp +{ + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + private void GetTransactionStatusButton_Click(object sender, EventArgs e) + { + //Use a transactionReference from your own transactions. 91ff1ed2-beee-44ca-96f9-9acec74dc659 is a test transactionReference + my.GetTransactionStatus("91ff1ed2-beee-44ca-96f9-9acec74dc659"); + } + } +} +``` + +Go back to Form1.cs[Design] and double click on each of the other buttons to automatically generate an OnClick method in Form1.cs. Link each of the buttons to the correct methods in MyClass.cs. + +```csharp +using System; +using System.Drawing; +using System.Windows.Forms; + +namespace GettingStartedApp +{ + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + + private void ConnectButton_Click(object sender, EventArgs e) + { + //my.DiscoverDevices(); + my.DirectConnect(); + } + + private void DisconnectButton_Click(object sender, EventArgs e) + { + my.Disconnect(); + } + } +} +``` + +### Let´s notify the user when the app is connected and ready to send the transaction + +**Update the ConnectionLabel to notify the user of the connection status** +Get the connection status from the method **[*ConnectionStatusChanged*](#7)** in MyClass.cs. + +```csharp +public void ConnectionStatusChanged(ConnectionStatus status, Device device) +{ + Console.WriteLine("*** ConnectionStatus *** " + status); + if (status == ConnectionStatus.Connected) + { + uIClass.UpdateLabel(true); + } + else + { + uIClass.UpdateLabel(false); + } +} + +public void CurrentTransactionStatus(StatusInfo info, Device device) +{ + //Let also console log the status during the transaction + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); +} + +Create the UpdateLabel method in Form1.cs + +public delegate void UpdateConnectionLabel(bool Connected); +public void UpdateLabel(bool Connected) +{ + //Only need to check for one of the webbrowsers + if (ConnectionLabel.InvokeRequired) + { + UpdateConnectionLabel d = new UpdateConnectionLabel(UpdateLabel); + this.Invoke(d, new object[] { Connected }); + } + else + { + if (Connected) + { + ConnectionLabel.Text = "Connected"; + ConnectionLabel.BackColor = Color.Green; + } + else { + ConnectionLabel.Text = "Disconnected"; + ConnectionLabel.BackColor = Color.Red; + } + } +} +``` + +### Let´s display the receipts at the end of a transaction! + +**1. Fetch the cardholder's and merchant receipts from the method EndOfTransaction in MyClass** +At this point all the buttons are connected but we are still missing to display the receipts in the webBrowsers. First, let´s get the receipts from the method EndOfTransaction in myClass.cs. + +```csharp +public void EndOfTransaction(TransactionResult transactionResult, Device device) +{ + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + uIClass.DisplayReceipts(result.MerchantReceipt, result.CustomerReceipt); +} +``` + +**2. Create the DisplayReceipts method in form1.cs** + +```csharp +public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); +public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) +{ + //Only need to check for one of the webbrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } +} +``` + +### Final Result! + +Here is how MyClass.cs and Form1.cs must eventually look like : + +**1. MyClass.cs :** + +```csharp +using System; +using System.Collections.Generic; +using System.Numerics; +using com.handpoint.api; + +namespace GettingStartedApp +{ + class MyClass : Events.Required, Events.Status + { + Hapi api; + Device myDevice; + private Form1 uIClass; + + public MyClass(Form1 form1) + { + uIClass = form1; + InitApi(); + } + + public void InitApi() + { + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret)); + } + + public void DiscoverDevices() + { + api.SearchDevices(ConnectionMethod.BLUETOOTH); + } + + public void DirectConnect() + { + Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH); + api.Connect(device); + } + + public bool Pay() + { + return api.Sale(new BigInteger(1000), Currency.GBP); + } + + public void Disconnect() + { + api.Disconnect(); + } + + public void ConnectionStatusChanged(ConnectionStatus status, Device device) + { + Console.WriteLine("*** ConnectionStatus *** " + status); + if (status == ConnectionStatus.Connected) + { + uIClass.UpdateLabel(true); + } + else + { + uIClass.UpdateLabel(false); + } + } + + public void CurrentTransactionStatus(StatusInfo info, Device device) + { + //Let's log also the status during the transaction + Console.WriteLine("*** CurrentTransactionStatus *** " + info.Status.ToString()); + } + public void DeviceDiscoveryFinished(List devices) + { + foreach (Device device in devices) + { + if (device.Name != null) + { + if (device.Name.Equals("PP0513901435")) + { + this.device = device; + api.Connect(this.device); + } + } + } + } + + public void EndOfTransaction(TransactionResult result, Device device) + { + Console.WriteLine("*** EndOfTransaction *** " + result.ToJSON()); + uIClass.DisplayReceipts(result.MerchantReceipt, result.CustomerReceipt); + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt. + } + + public void HardwareStatusChanged(HardwareStatus status, ConnectionMethod hardware) + { + //Ignore + } + } +} +``` + +**2. Form1.cs :** + +```csharp +using System; +using System.Drawing; +using System.Windows.Forms; + +namespace GettingStartedApp +{ + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + + private void PayButton_Click(object sender, EventArgs e) + { + my.Pay(); + } + + private void ConnectButton_Click(object sender, EventArgs e) + { + my.DirectConnect(); + } + + private void DisconnectButton_Click(object sender, EventArgs e) + { + my.Disconnect(); + } + + public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); + public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) + { + //Only need to check for one of the webbrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } + } + + public delegate void UpdateConnectionLabel(bool connected); + + public void UpdateLabel(bool Connected) + { + //Only need to check for one of the webbrowsers + if (ConnectionLabel.InvokeRequired) + { + UpdateConnectionLabel d = new UpdateConnectionLabel(UpdateLabel); + this.Invoke(d, new object[] { Connected }); + } + else + { + if (Connected) + { + ConnectionLabel.Text = "Connected"; + ConnectionLabel.BackColor = Color.Green; + } + else { + ConnectionLabel.Text = "Disconnected"; + ConnectionLabel.BackColor = Color.Red; + } + } + } + + } +} +``` + +### Let's run our program! + +Run the program by clicking the "play" button : + +1. Click on "Connect To Card Reader", this can take a little bit of time (10 sec max) due to the fact that we are looking for all the devices around before connecting to a specific one +2. Click "Pay Now" +3. Follow the instructions on the card reader +4. When the transaction is finished, the receipts should be displayed in the webBrowsers +5. Click on "Disconnect From Card Reader" to stop the connection with the card reader + +## Terminal Simulator Integration + +### Introduction + +This tutorial is guiding you through all the steps to create a basic payment application for Windows using a card reader simulator. The simulator only has limited capabilities and we highly recommend that you order a development kit if you want to carry a full integration. The development kit contains a card reader as well as a test card and will allow you to test your integration from end to end. + +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. + +### Connecting to the simulator + +The SDK offers a method in which you will need to specify the card reader to be used: + +```csharp +hapi.Connect(new Device("Name", "Port", "Address", ConnectionMethod.****)) +``` + +Simply set the ConnectionMethod to Simulator, i.e. ConnectionMethod.Simulator. The SDK does the rest. You don't need to search via bluetooth for surrounding card readers when using the simulator. + +```csharp +hapi.Connect(new Device("Name", "Port", "Address", ConnectionMethod.Simulator)) +``` + +### Controlling responses + +The simulator mimics the card reader as much as possible regarding information flow from the SDK interface to your application. It will return all the transaction statuses, transaction results and receipts. + +Results of a transaction are controlled by the amount sent into the sale function:
+The 3rd position from the right sets the desired financial status, 0 = Authorized and 1 = Declined.
+The 4th position from the right sets the desired verification method, 0 = Signature and 1 = PIN. + +```csharp +hapi.Sale(X10XX, Currency.GBP); // amount = X 10 XX - where X represents an integer [0;9] +``` + +- X 00 XX = Signature authorized +- X 01 XX = Signature declined +- X 10 XX = Pin authorized +- X 11 XX = Pin declined + +### Let's start programming! + +**1. Create a C# class** +Create a new C# class called MyClass and include com.handpoint.api as a dependency : + +```csharp + using System; + using System.Collections.Generic; + using System.Linq; + using System.Text; + using com.handpoint.api; + + namespace GettingStartedWithSimulator + { + class MyClass + { + } + } +``` + +**2. Initialize the API** + +```csharp + using System; + using System.Collections.Generic; + using System.Linq; + using System.Text; + using com.handpoint.api; + + namespace GettingStartedWithSimulator + { + class MyClass + { + Hapi api; + + public MyClass() + { + InitApi(); + } + 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! + // The shared secret is a unique string shared between the card reader and your mobile application. + // It prevents other people to connect to your card reader. + } + } + } +``` + +**3. Implement the mandatory Events(Events.Required)** + +```csharp + using System; + using System.Collections.Generic; + using System.Linq; + using System.Text; + using com.handpoint.api; + + namespace GettingStartedWithSimulator + { + class MyClass : Events.Required + { + Hapi api; + + public MyClass() + { + InitApi(); + } + + 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! + // The shared secret is a unique string shared between the card reader and your mobile application + // It prevents other people to connect to your card reader + } + + public void DeviceDiscoveryFinished(List devices) + { + // Only needed when using a payment terminal + //here you get a list of Bluetooth payment terminals paired with your PC + // You can also get a list of serial / USB payment terminals attached to your computer + + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + + api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt + // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it + } + + public void EndOfTransaction(TransactionResult transactionResult, Device device) + { + // The object TransactionResult holds the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + } + } +``` + +**4. Add a method to connect to the simulator** + +```csharp + public void Connect() + { + Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR); + api.Connect(device); + } +``` + +**5. Add a method to take payments with the simulator** + +The simulator mimics the card reader as much as possible regarding the information flow from the SDK interface to your application. The results of the transaction (declined, authorized) and the type of verification method (PIN, signature) will depend on the amount used. + +You can get different responses from the simulator by setting different values for the amount parameter, e.g. for a Sale function : + +```csharp + api.Sale(X10XX, Currency.GBP); // amount = X 10 XX - where X represents an integer [0;9] +``` + +**Amount Values** + +- X00XX = Signature authorized +- X01XX = Signature declined +- X10XX = PIN authorized +- X11XX = PIN declined + +The 3rd number from right sets desired financial status, Authorized or Declined. Default status is Authorized.
+The 4th number from right sets desired verification method, Signature or PIN. Default method is Signature. + +Let´s add 4 methods to MyClass in order to represent the 4 cases above : + +```csharp + using System; + using System.Collections.Generic; + using System.Linq; + using System.Text; + using com.handpoint.api; + + namespace GettingStartedWithSimulator + { + class MyClass : Events.Required + { + Hapi api; + + public MyClass() + { + InitApi(); + } + + 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! + // The shared secret is a unique string shared between the card reader and your mobile application. + // It prevents other people to connect to your card reader. + } + + public void DeviceDiscoveryFinished(List devices) + { + // Only needed when using a payment terminal + //Here you get a list of Bluetooth payment terminals paired with your PC + // You can also get a list of serial / USB payment terminals attached to your computer + + } + + public void Connect() + { + Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR); + api.Connect(device); + } + + public bool PayWithSignatureAuthorized() + { + return api.Sale(new BigInteger("10000"), Currency.GBP); + // amount X00XX where X represents an integer [0;9] --> Signature authorized + } + + public bool PayWithSignatureDeclined() + { + return api.Sale(new BigInteger("10100"), Currency.GBP); + // amount X01XX where X represents an integer [0;9] --> Signature declined + } + + public bool PayWithPinAuthorized() + { + return api.Sale(new BigInteger("11000"), Currency.GBP); + // amount X10XX where X represents an integer [0;9] --> PIN authorized + } + public bool PayWithPinDeclined() + { + return api.Sale(new BigInteger("11100"), Currency.GBP); + // amount X11XX where X represents an integer [0;9] --> PIN declined + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + + api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt. + // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it + } + + public void EndOfTransaction(TransactionResult transactionResult, Device device) + { + // The object TransactionResult stores the different receipts + // Other information can be accessed through this object like the transaction ID, the amount... + } + } + } +``` + +### Let's create a User Interface! + +**1. Create buttons** + +- Go to your user interface (usually Form1.cs[Design]) +- Select View > Toolbox +- In the toolbox, under “Common Controls” drag and drop 5 button items to the user interface +- Select "button1" > Right-Click > Properties +- Change the attribute "Name" from "button1" to "ConnectToSimulator" +- Change the attribute "text" from "button1" to "Connect To Simulator" +- Change the attribute "Name" from "button2" to "PayWithSignatureAuthorized" +- Change the attribute "text" from "button2" to "Pay With Signature Authorized" +- Change the attribute "Name" from "button3" to "PayWithSignatureDeclined" +- Change the attribute "text" from "button3" to "Pay With Signature Declined" +- Change the attribute "Name" from "button4" to "PayWithPinAuthorized" +- Change the attribute "text" from "button4" to "Pay With Pin Authorized" +- Change the attribute "Name" from "button5" to "PayWithPinDeclined" +- Change the attribute "text" from "button5" to "Pay With Pin Declined" + +**2. Create WebBrowsers** + +Now that we have our 5 buttons let´s create two webBrowsers items to display the merchant receipt as well as the cardholder´s receipt at the end of the transaction. + +- Select View > Toolbox > Common Controls > WebBrowser +- Drag and drop two web browsers to the user interface +- Select View > Toolbox > Common Controls > Label +- Drag and drop two labels to the user interface in order to identify the webBrowser items +- Change the attribute "Name" from the left webBrowser to "MerchantReceiptBrowser" +- Change the attribute "Name" from the right webBrowser to "CardholderReceiptBrowser" +- Change the attribute "Name" from "label1" to "MerchantReceiptLabel" +- Change the attribute "text" from "label1" to "Merchant Receipt :" +- Change the attribute "Name" from "label2" to "CardholderReceiptLabel" +- Change the attribute "text" from "label2" to "Cardholder Receipt :" + +### Let's link our user interface with methods! + +**1. Referencing the user interface(Form1.cs) in MyClass** + +In MyClass.cs, create an instance of Form1 called UIClass and initialize it. Instantiate MyClass and add form1 as a parameter for the Class. + +```csharp + class MyClass : Events.Required + { + Hapi api; + private Form1 UIClass; + + public MyClass(Form1 form1) + { + InitApi(); + UIClass = form1; + } +``` +**2. Referencing Myclass in Form1.cs and link methods to the user interface** + +Go to Form1.cs[Design] and double click on the button "Connect To Simulator". By Double Clicking on the "Connect To Simulator" button you created a method called ConnectToSimulator_Click. Create a new instance of MyClass called "my" in Form1.cs then, inside the new method ConnectToSimulator_Click call the Connect() method from MyClass. + +```csharp + using System; + using System.Collections.Generic; + using System.ComponentModel; + using System.Data; + using System.Drawing; + using System.Linq; + using System.Text; + using System.Windows.Forms; + namespace GettingStartedWithSimulator + { + public partial class Form1 : Form + { + MyClass my; + + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + private void ConnectToSimulator_Click(object sender, EventArgs e) + { + my.Connect(); + } + } + } +``` + +Go back to Form1.cs[Design] and double click on each of the other buttons to automatically generate an OnClick method in Form1.cs. Link each of the buttons to the correct methods in MyClass.cs. + +```csharp + using System; + using System.Collections.Generic; + using System.ComponentModel; + using System.Data; + using System.Drawing; + using System.Linq; + using System.Text; + using System.Windows.Forms; + namespace GettingStartedWithSimulator + { + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + private void ConnectToSimulator_Click(object sender, EventArgs e) + { + my.Connect(); + } + private void PayWithSignatureAuthorized_Click(object sender, EventArgs e) + { + my.PayWithSignatureAuthorized(); + } + private void PayWithSignatureDeclined_Click(object sender, EventArgs e) + { + my.PayWithSignatureDeclined(); + } + private void PayWithPinAuthorized_Click(object sender, EventArgs e) + { + my.PayWithPinAuthorized(); + } + private void PayWithPinDeclined_Click(object sender, EventArgs e) + { + my.PayWithPinDeclined(); + } + } + } +``` + +### Let´s display the receipts at the end of a transaction! + +**1. Fetch the cardholder's and merchant receipts from the method EndOfTransaction in MyClass** + +At this point all the buttons are connected but we are still missing to display the receipts in the webBrowsers. First, let´s get the receipts from the method EndOfTransaction in myClass.cs. + +```csharp + public void EndOfTransaction(TransactionResult transactionResult, Device device) + { + UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt); + } +``` + +**2. Create the DisplayReceipts method in form1.cs** + +```csharp + public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); + public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) + { + //Only need to check for one of the webBrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } + } +``` + +### Final Result! + +Here is how MyClass.cs and Form1.cs must eventually look like : + +**1. MyClass.cs :** + +```csharp + using System; + using System.Collections.Generic; + using System.Linq; + using System.Text; + using com.handpoint.api; + namespace GettingStartedWithSimulator + { + class MyClass : Events.Required + { + Hapi api; + private Form1 UIClass; + public MyClass(Form1 form1) + { + InitApi(); + UIClass = form1; + } + + 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! + // The shared secret is a unique string shared between the card reader and your mobile application. + // It prevents other people to connect to your card reader. + } + + public void DeviceDiscoveryFinished(List devices) + { + // Only needed when using a payment terminal + //Here you get a list of Bluetooth payment terminals paired with your PC + // You can also get a list of serial / USB payment terminals attached to your computer + + } + + public void Connect() + { + Device device = new Device("Name", "Address", "Port", ConnectionMethod.SIMULATOR); + api.Connect(device); + } + + public bool PayWithSignatureAuthorized() + { + return api.Sale(new BigInteger("10000"), Currency.GBP); + // amount X00XX where X represents an integer [0;9] --> Signature authorized + } + + public bool PayWithSignatureDeclined() + { + return api.Sale(new BigInteger("10100"), Currency.GBP); + // amount X01XX where X represents an integer [0;9] --> Signature declined + } + + public bool PayWithPinAuthorized() + { + return api.Sale(new BigInteger("11000"), Currency.GBP); + // amount X10XX where X represents an integer [0;9] --> PIN authorized + } + public bool PayWithPinDeclined() + { + return api.Sale(new BigInteger("11100"), Currency.GBP); + // amount X11XX where X represents an integer [0;9] --> PIN declined + } + + public void SignatureRequired(SignatureRequest signatureRequest, Device device) + { + // You'll be notified here if a sale process needs a signature verification + // A signature verification is needed if the cardholder uses an MSR or a chip & signature card + // This method will not be invoked if a transaction is made with a Chip & PIN card + + + api.SignatureResult(true); // This line means that the cardholder ALWAYS accepts to sign the receipt. + // A specific line will be displayed on the merchant receipt for the cardholder to be able to sign it + } + + public void EndOfTransaction(TransactionResult transactionResult, Device device) + { + UIClass.DisplayReceipts(transactionResult.MerchantReceipt, transactionResult.CustomerReceipt); + } + } + } +``` + +**2. Form1.cs :** + +```csharp + using System; + using System.Collections.Generic; + using System.ComponentModel; + using System.Data; + using System.Drawing; + using System.Linq; + using System.Text; + using System.Windows.Forms; + namespace GettingStartedWithSimulator + { + public partial class Form1 : Form + { + MyClass my; + public Form1() + { + InitializeComponent(); + my = new MyClass(this); + } + private void ConnectToSimulator_Click(object sender, EventArgs e) + { + my.Connect(); + } + private void PayWithSignatureAuthorized_Click(object sender, EventArgs e) + { + my.PayWithSignatureAuthorized(); + } + private void PayWithSignatureDeclined_Click(object sender, EventArgs e) + { + my.PayWithSignatureDeclined(); + } + private void PayWithPinAuthorized_Click(object sender, EventArgs e) + { + my.PayWithPinAuthorized(); + } + private void PayWithPinDeclined_Click(object sender, EventArgs e) + { + my.PayWithPinDeclined(); + } + + public delegate void UpdateReceiptsCallback(string MerchantReceipt, string CustomerReceipt); + public void DisplayReceipts(string MerchantReceipt, string CustomerReceipt) + { + //Only need to check for one of the webbrowsers + if (MerchantReceiptBrowser.InvokeRequired) + { + UpdateReceiptsCallback d = new UpdateReceiptsCallback(DisplayReceipts); + this.Invoke(d, new object[] { MerchantReceipt, CustomerReceipt }); + } + else + { + MerchantReceiptBrowser.DocumentText = MerchantReceipt; + CardholderReceiptBrowser.DocumentText = CustomerReceipt; + } + } + } + } +```` + +### Let's run our program! + +Run the program by clicking the "play" button, click on "Connect to simulator" and then Click on one of the payment types available and have a look at the receipts! Voila! diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintroduction.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintroduction.md new file mode 100644 index 0000000..20a42d4 --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsintroduction.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 1 +id: windowsintroduction +--- + + +# Introduction + +
+
+
+

Windows SDK

+
+
+ + + +
+
+

Get the latest Windows SDK!

+

If you are integrating your software with a PAX debug terminal you will need to use the x.x.x-beta version of the SDK.

+

If you are integrating your software with a PAX production terminal you will need to use the x.x.x version of the SDK.

+

If you are integrating your software with an HiLite terminal you will need to to use the x.x.x version of the SDK.

+
+
+
+ +

+ +The new generation of Handpoint APIs and SDKs are engineered to make your life simpler, happier. + +**Awesomely simple** + +Created for humans, coders, geeks, no need of dark and complex knowledge of the payment industry. + +**Superly secure** + +We take care of the PCI side so you don't have to spend months becoming compliant. +The Handpoint card reader encrypts all sensitive cardholder data so your app does not have to deal with it. + +**Working with the SDK** + +The Handpoint Windows SDK is compatible with .NET Framework Version 4.6.1. + +1. Download the SDK. +2. Create a new windows form project in Visual Studio 2010 (or above) using .Net Framework Version 4.6.1. +3. Add the [HandpointSDK NuGet Package](https://www.nuget.org/packages/HandpointSDK/) to your project. +If you have a DEBUG device [(How to identify DEBUG devices)](https://handpoint.atlassian.net/wiki/spaces/PD/pages/1578401793/How+to+Identify+Between+Development+and+Production+Terminals) please use the package version -beta (prerelease): Example 3.0.0-beta +4. Follow the getting started guide, to get you up and running or dive into the documentation. + +If you have any questions, do not hesitate to [contact us](mailto:support@handpoint.com). \ No newline at end of file diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowsobjects.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsobjects.md new file mode 100644 index 0000000..043127c --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsobjects.md @@ -0,0 +1,619 @@ +--- +sidebar_position: 9 +id: windowobjects +--- + + +# Objects + +## Card Entry Type{#22} + +`CardEntryType` Enum + +An enum representing different card entry types. + +** Possible values ** + +`UNDEFINED` `MSR` `ICC` `CNP` + +## Card Scheme Name{#23} + +`CardSchemeName` Enum + +An enum representing different card brands. + +**Possible values** + +`MasterCard` `Visa` `Maestro` `American Express` `Discover` `JCB` `Diners` `UnionPay` `Interac` + + +## Connection Method{#12} + +`ConnectionMethod` Enum + +An enum representing different types of connection methods. + +`BLUETOOTH`, `CLOUD` and `SIMULATOR` are supported for Windows. + +Possible values +`USB` `SERIAL` `BLUETOOTH` `CLOUD` `HTTPS` `WIFI` `ETHERNET` `SIMULATOR` + + +## Connection Status{#18} + +`ConnectionStatus` Enum + +A list of statuses given to a connection. + +**Possible values** + +`Connected` `Connecting` `Disconnected` `Disconnecting` `Initializing` `NotConfigured` + + +## Currency{#1} + +`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{#2} + +`Device` Object + +An object to store the information about the payment terminal in use. + +**Constructor** + +Device( String name , String address , String port , ConnectionMethod [*connectionMethod*](#12) , String sharedSecret , int timeout ); + +| Parameter | Notes | +| ----------- | ----------- | +| `name` Required
*String* |A name to identify the payment terminal| +| `address` Required
*String* | The address of the device you wish to connect to. E.g.: "08:00:69:02:01:FC" for bluetooth or "9822032398-PAXA920" for CLOUD (composition of serial number and model of the target device) .| +| `port` Required
*String* | The port to connect to.| +| `connectionMethod` Required
[*ConnectionMethod*](#12) | The type of connection with the device. E.g: Bluetooth, Cloud, Serial, etc.| +| `sharedSecret`
*String* | This parameter can be used to change the default shared secret for the payment terminal| +| `timeout`
*int* | The number of miliseconds after which the connection is considered timed out| + +**Code example** + +```csharp +//Create and init a new HiLite payment terminal +Device dev = new Device("CardReader7", "08:00:69:02:01:FC", "1", ConnectionMethod.BLUETOOTH); + +//Create and init a new PAX/Telpo payment terminal +Device dev = new Device("CloudDevice", "9822032398-PAXA920", "", ConnectionMethod.CLOUD); +// The address is the composition of the serial number and model ot the target device. +//Example for a PAX A920 device: serial_number - model -> 9822032398-PAXA920 +``` +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `Id`
*String* | A unique identifier for the device.| + + +## Device Parameter{#8} + + +`DeviceParameter` Enum + +An enum describing all the available commands to send to a device. + +**Possible values** + +`BluetoothName` `BluetoothPass` `SystemTimeout` `ScreenTimeout` `SignatureTimeout` +`Language` + + + +## Device Status{#24} + + +`DeviceStatus` Enum + +A class that holds the device status. + +**Properties** + +|Property |Description| +| ----------- | ----------- | +|`SerialNumber`
*String* |Gets the serial number of the device| +|`BatteryStatus`
*String*| Gets the battery status in percentages of the device.| +|`BatterymV`
*String* | Gets the battery milli volts of the device.| +|`BatteryChargingt`
*String*| Gets the battery charging status of the device.| +|`ExternalPower`
*String* | Gets the status of an external power source for the device.| +|`ApplicationName`
*String*| Gets the application name used by the device.| +|`ApplicationVersion`
*String*| Gets the application version number used by the device.| + + + +## Financial Status{#25} + + +`FinancialStatus` Enum + +An enum representing different final statuses of a 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](windowsdevicemanagement.md#get-transaction-status) method. This status means that the transaction does not exist in the Handpoint gateway. If this status is returned within 90s of the start of a transaction, there could be a chance that the cardholder has not inserted, swiped or tapped his card yet on the terminal and the Handpoint gateway might soon receive the transaction. If the `UNDEFINED` status is returned after 90s, it means that the transaction processed has not reached the Handpoint gateway and it will NOT be charged.| +| `AUTHORISED`
| The transaction (Sale, Refund etc.) has been authorised. Consider this value as "successful". | +| `DECLINED`
| The transaction has been declined by the acquirer or issuer. | +| `PROCESSED`
| The `printReceipt` operation was successful.| +| `FAILED`
| Status generated due to a network error, a card which can not be read etc. As a general rule, errors are mapped to `FAILED`. This means the operation was unsuccessful and the transaction has not been charged. | +| `CANCELLED`
| The transaction has been cancelled. For example if the `stopCurrentTransaction` operation has been used or the cancel button on the terminal has been pressed. | +| `PARTIAL_APPROVAL`
| A partial approval is returned by the acquirer when funds have been partially authorized, for example if the cardholder does not have all the funds to cover the entire cost of the goods or services they are buying. The merchant can obtain the remainder of the purchase amount in another form of payment (cash, check or another card transaction for the remaining). `PARTIAL_APPROVAL` is **only** applicable to the United States market. | +| `IN_PROGRESS` *
| The `IN_PROGRESS` status can be returned as a response to the [get transaction status](windowsdevicemanagement.md#get-transaction-status) method. The transaction is known by the gateway but the result is not available yet. Please check the status again after a few seconds. | +| `REFUNDED` *
| The `REFUNDED` status can be returned as a response to the [get transaction status](windowsdevicemanagement.md#get-transaction-status) method. The original transaction (sale) has been refunded. | +| `CAPTURED`
| The pre-authorization has been captured and funds are being moved to the merchant account. The `CAPTURED` financial status will only be returned in case a [preAuthorizationCapture](windowstransactions.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](windowsdevicemanagement.md#get-transaction-status) method. + + + +## Handpoint API (Hapi) factory + +`HapiFactory` Object + +A factory to provide a unified entrypoint and to simplify the way to instantiate the Hapi (SDK) object. + +**Methods** + +**Static factory** +getAsyncInterface( Events.Required requiredListener , HandpointCredentials handpointCredentials ); + +| Parameter | Notes | +| ----------- | ----------- | +| `requiredListener` Required
*Events.Required* | A listener object to report the required events.| +| `handpointCredentials` Required
[*HandpointCredentials*](#30) | Object containing the user's shared secret and/or Cloud Api Key.| + +**Code example** + +```csharp +//InitApi for HiLite payment terminals +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 +} + +//InitApi for Cloud payment terminals (PAX/Telpo) +public void InitApi() +{ + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-Is-The-Merchant-Api-Key"; + api = HapiFactory.GetAsyncInterface(this, new HandpointCredentials(sharedSecret, apikey)); + //The api is now initialized. Yay! we've even set a default shared secret and the merchant Api Key! +} +``` + +## Handpoint Credentials{#30} + +`HandpointCredentials` Object + +A class containing information related to the user credentials. + +**Properties** + +| Parameter | Notes | +| ----------- | ----------- | +| `SharedSecret`
*String* | `String` the value of the shared secret (provided by Handpoint), only required when using BLUETOOTH as connection method. If using CLOUD this value can be any non-null string.| +| `CloudApiKey`
*String* | `String` the value of the merchant Cloud Api Key (provided by Handpoint), only required when using CLOUD as connection method.| + +**Code example** + +```csharp +{ + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + new HandpointCredentials(sharedSecret); + //We've set a default shared secret! +} + +{ + string sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132"; + string apikey = "This-Is-The-Merchant-Api-Key"; + new HandpointCredentials(sharedSecret, apikey); + //We've set a default shared secret and the merchant Api Key! +} +``` + + +## Hapi Manager + +`HapiManager` Object + +A static class containing information about the current status of the SDK + +** Properties ** + + +|Property |Description| +| ----------- | ----------- | +|`DefaultSharedSecret`
*String* |Gets the default shared secret used in the SDK.| +|`LogLevel`
[*LogLevel*](#9) |Gets the current log level of the SDK and payment terminal.| +|`inTransaction`
*bool* |Checks whether the SDK is in transaction or not. True if the SDK is in transaction, false otherwise. This might return a true if there is a communication error between the SDK and payment terminal but the transaction has been completed on the card reader.| +|`SdkVersion`
*String* |Gets the current Sdk version.| +|`IsTransactionResultPending`
*boolean* |In case of a communication failure between the device and the API a [*Transaction Result*](#14) might not be delivered to the API. This function checks if there is a pending [*Transaction Result*](#14). This field is only updated when connecting to a device. If this function returns true the [*Transaction Result*](#14) (which includes the receipt) can be fetched with hapi.GetPendingTransactionResult();. This function serves the same functionality as the event PendingTransactionResult(Device device), so every time that event is invoked, HapiManager.IsTransactionResultPending() is true until the result is fetched.| +|`Settings.AutoRecoverTransactionResult`
*boolean* |In case of a communication failure between the device and the API a [*Transaction Result*](#14) might not be delivered to the API. This property can be set to true or false. If set to true, the SDK will automatically fetch the pending [*Transaction Result*](#14) when detected and return it via [*TransactionResultReady*](#11). The function PendingTransactionResult is never invoked if this property is set to true. If set to false PendingTransactionResult will be called when a TransactionResult is pending.| + +**Code example** + +```csharp +//Check if the SDK is in transaction +bool inTransaction = HapiManager.InTransaction(SomeConnectedDevice); +//Check the current logLevel +LogLevel level = HapiManager.GetLogLevel(); +``` + + + +## Log Level{#9} + + +`LogLevel` Enum + +An enum describing the different levels of logging used in the SDK and the payment terminal. + +**Possible values** + +`None` `Info` `Full` `Debug` + + +## Metadata{#metadata} + +`Metadata` Object + +Object used to echo metadata1-5, in the transaction result, if it was set as an optional parameter in the transaction request . + +**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 + +`MoneyRemitanceOptions` 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))| + + +```csharp +Dictionary map = new Dictionary(); + +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); +``` + + +## Operation Start Result{#OperationStartResult} + +`OperationStartResult` Object + +Object containing information about the financial operation being performed. + +|Property |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{#3} + +`OptionalParameters` Object + +A class containing optional transaction parameters now supported by the device. + +**Properties** + + +|Property| 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 amount 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. Example: "03" or "24".| +|`CustomerReference`
*String*|**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 36 characters and received back when the transaction has been processed. Example: "C.nr. 212311".| +|`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.| +|`DuplicateCheck`
*String*| 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 DuplicateCheck functionality is available for the following transactions:** Sale, Sale and Tokenize, Sale Reversal, Refund and Refund Reversal.


The Duplicate Check service is **enabled by default**, if you want to disable it, you must use the `String` "0", for example: ```options.Add(XmlTag.DuplicateCheck.Tag(), "0");```| +| `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.| +| `Metadata1`
*String*|**String Metadata1 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata1.Tag(), "Data 1");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `Metadata2`
*String*|**String Metadata2 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata2.Tag(), "Data 2");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `Metadata3`
*String*|**String Metadata3 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata3.Tag(), "Data 3");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `Metadata4`
*String*|**String Metadata4 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata4.Tag(), "Data 4");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `Metadata5`
*String*|**String Metadata5 is available for all transactions.**
A ` String` used to store any required data (max length 250 characters). This information will be echoed inside the Metadata object in the transaction result. Example: ```options.Add(XmlTag.Metadata5.Tag(), "Data 5");```.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| +| `MoneyRemittanceOptions`
[*MoneyRemittanceOptions*](windowsobjects.md#money-remittance-options) | An object representing options for Mastercard money remittance transactions.| + + +## Payment Scenario{#26} + +`PaymentScenario` Enum + +An enum representing different types of payment scenarios. + +** Possible values ** + +`UNKNOWN` `MAGSTRIPE` `MAGSTRIPECONTACTLESS` `CHIP` `CHIPCONTACTLESS` `CHIPFAILMAGSTRIPE` `MOTO` + + +## Signature Request{#17} + +`SignatureRequest` Object + +A class containing information about a signature request or verification. + +**Properties** + +|Property| Description| +| ----------- | ----------- | +|Timeout
*Int* |The value of the timeout in seconds.| +|MerchantReceipt
*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. | + + +## Status + +`status` Enum + +An enum containing information about the status of the 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} + +`statusInfo` Object + +A class containing information about the status of the transaction. + +**Properties** + + +|Property |Description| +| ----------- | ----------- | +|`CancelAllowed`
*bool* |A `bool` allowing the user to know if the payment terminal will accept a cancel 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*](#24) |A `DeviceStatus` object containing information about the payment terminal.| + + +## Tender Type{#27} + +`TenderType` Enum + +An enum representing different tender types. + +** Possible values** + +`NOT_SET` `CREDIT` `DEBIT` + + +## Terminal Parameters + +`TerminalType` Enum + +An enum describing parameters supported by the payment terminal. + +**Possible values** + +`BluetoothName` `BluetoothPass` `SystemTimeout` `ScreenTimeout` `SignatureTimeout` +`Language` + + + +## Transaction Result Object{#14} + +`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** + +| Parameter | Notes | +| ----------- | ----------- | +| `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`
*BigInteger* | 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*](#23) | 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*](#1) | 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*](#24) | Status of the payment terminal| +| `dueAmount`
*BigString* | 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`
*BigString* | 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*](#25) | The financial status contains the outcome of the transaction. For example "AUTHORISED" or "DECLINED"| +| `gratuityAmount` :triangular_flag_on_post:
*BigInteger* | This field will be deprecated in Windows SDK 5.0.0 version, please use the **tipAmount** field
Gratuity (tip) amount, if any, in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `gratuityPercentage` :triangular_flag_on_post:
*double* | This field will be deprecated in Windows SDK 5.0.0 version, please use the **tipPercentage** field
If tipping is enabled, this field will return the tip percentage added on top of the base amount| +| `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[1-5] was provided as an optional parameter in the transaction request it is echoed unaltered in this object| +| `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*](#26) | 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*](#27) | 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*](#28) | 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*](#29) | cardholder verification method, for example "PIN"| + +**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": "", + "metadata3": "", + "metadata4": "", + "metadata5": "" + }, + "mid": "", + "originalEFTTransactionID": "", + "paymentScenario": "CHIPCONTACTLESS", + "rrn": "", + "signatureUrl": "", + "statusMessage": "Approved or completed successfully", + "tenderType": "CREDIT", + "tid": "ACQUIRER_TID", + "gratuityAmount": 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, + "gratuityPercentage": 0, + "recoveredTransaction": false +} +``` + + +## Transaction Type{#28} + +`TransactionType` Enum + +An enum representing different types of transactions. + +**Possible values** + +`UNDEFINED` `SALE` `VOID_SALE` `REFUND` `VOID_REFUND` `CANCEL_SALE` `CANCEL_REFUND` `TOKENIZE_CARD` `SALE_AND_TOKENIZE_CARD` `REVERSAL` `UPDATE` `HOST_INIT` `PRINT_RECEIPT` `CARD_PAN` `CANCEL_TRX` `MOTO_SALE` `MOTO_REFUND` `MOTO_REVERSAL` + + +**Code example** + +```csharp +//Currently CLOUD, BLUETOOTH, and SIMULATOR are the only ConnectionMethod available. +public enum ConnectionMethod +{ + USB, + SERIAL, + HTTPS, + WIFI, + ETHERNET, + BLUETOOTH, + CLOUD, + SIMULATOR +} +``` + + +## Verification Method{#29} + +`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/windows_versioned_docs/version-Windows SDK 4.4.0/windowsreleasenotes.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsreleasenotes.md new file mode 100644 index 0000000..2962972 --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowsreleasenotes.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 2 +id: windowsreleasenotes +--- + +# Release Notes + +:::tip +Don’t miss any updates on our latest releases. Contact your Handpoint relationship manager to subscribe to the Handpoint Newsletter! +::: + +## 4.4.0 +**Features:** + +A new `cardPresent` parameter is available under [Optional Transaction Parameters](windowsobjects.md#3). 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. + +## 4.3.1 +**Features:** + +A new `tokenize` parameter is available under [Optional Transaction Parameters](windowsobjects.md#3). 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. + +## 4.2.0 +**Features:** + +We're excited to announce the latest update to our Windows 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](windowsobjects.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 only available for some acquirers and geographies. Please check with your Handpoint relationship manager about the availability of this functionality for your merchants. + + +## 4.1.0 +**Features**: + +We are introducing a new transaction type called [Pre-Authorization](windowstransactions.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](windowstransactions.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](windowstransactions.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](windowstransactions.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. + +## 4.0.0 + +**BREAKING CHANGE:** + +We are introducing a new feature called [Get Transaction Status](windowsdevicemanagement.md#get-transaction-status). 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](windowsobjects.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. + +All financial operations will now be returning an [OperationStartResult](windowsobjects.md#OperationStartResult) object instead of a boolean to indicate that the operation was successfully sent to the payment terminal: +The `transactionReference` field is a unique identifier for the transaction that you will receive immediately after sending the transaction request to the terminal. If for any reason you do not receive the [TransactionResult](windowsobjects.md#14) object at the end of the transaction you will now be able to use the `transactionReference` to directly query our Gateway and know instantly if the transaction for which you do not know the outcome was approved or declined. + +## 3.4.0 +**Features** + +We are introducing a new feature called [Transaction Metadata](windowsobjects.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. + +## 3.3.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. You do not need to update to v3.3.0 to benefit from this new feature. v3.3.0 will only allow you to disable the duplicate payment check feature if you wish to not support it. + +Here is an example showing how to disable the duplicate payment check functionality: +```csharp +Dictionary options = new Dictionary(); +options.Add(XmlTag.DuplicateCheck.Tag(), "0"); +hapi.Sale(amount, currency, options); +``` + +## 3.2.6 +- Cloud dependencies update (NewtonSoft Lib) + +## 3.2.5 + +**Fixes:** +- Nullpointer Exception on Cloud connect without network connection. +- Cloud dependencies update. +- Connection handling on transitions states: Connecting and Disconnecting. +- Automatic Cloud reconnection handling. +- Unable to manually disconnect during a transaction. + + +## 3.2.4 +**Fixes:** +- `SignatureResult` method. Signature result is always true no matter what is passed to the method. + +## 3.2.3 +**Fixes:** +- Crash on signature result (DATECS) + +## 3.2.1 +- Improved SDK reconnection logic in case of network unstability. + +## 3.2.0 + +**CLOUD Features:** + +- Mail Order/Telephone Order (MoTo). +- StopCurrentTransaction operation. + +## 3.1.7 + +**Fixes:** + +- CLOUD: Improved initial retry mechanism for triggering transactions. +- CLOUD: Increased initial timeout for triggering transactions. + + + diff --git a/windows_versioned_docs/version-Windows SDK 4.4.0/windowstransactions.md b/windows_versioned_docs/version-Windows SDK 4.4.0/windowstransactions.md new file mode 100644 index 0000000..dff9125 --- /dev/null +++ b/windows_versioned_docs/version-Windows SDK 4.4.0/windowstransactions.md @@ -0,0 +1,938 @@ +--- +sidebar_position: 5 +id: windowstransactions +--- + + +# Transaction Types + +:::caution +Since [**Windows SDK 3.3.0**](windowsreleasenotes#330) the Duplicate Check service it will be **enabled by default** when Handpoint Payments app **v4.0.0.** or higher is used. (Handpoint **Android SDK 7.0.0** or higher). +::: + +## Sale + +`Sale` Method + +A sale initiates a transaction with the payment terminal. In it's simplest form you only have to pass the **amount** and **currency** but it also accepts a map with optional parameters. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the transaction.| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3) (Customer reference, [Metadata](windowsobjects.md#metadata), [Money Remittance Options](windowsobjects.md#money-remittance-options),...). This object can be empty if no options are required.| + + +**Code example** + +```csharp +// Basic +this.Hapi.Sale(new BigInteger("1000"), Currency.EUR); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); + +this.Hapi.Sale(new BigInteger("1000"), Currency.EUR, map); +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry' +*** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + + **Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 + +`SaleAndTokenizeCard` 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
*BigInteger* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the transaction.| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3) (Customer reference, [Metadata](windowsobjects.md#metadata), [Money Remittance Options](windowsobjects.md#money-remittance-options),...). This object can be empty if no options are required.| + +**Code example** + +```csharp +//Initiate a sale for 10.00 in Great British Pounds +api.SaleAndTokenizeCard(new BigInteger("1000"),Currency.GBP); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); + +api.SaleAndTokenizeCard(new BigInteger("1000"), Currency.EUR, map); +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry' +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 + +`SaleReversal` Method + +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 optional 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* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the transaction.| +| `originalTransactionID` Required
*String* | Id of the original sale transaction (EFTTransactionID)| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowobjects#3)| + +**Code example** + +```csharp +//Initiate a reversal for 10.00 Pounds +api.SaleReversal(new BigInteger(1000),Currency.GBP,"00000000-0000-0000-0000-000000000000"); +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry' +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 + +`Refund` Method + +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 optional 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* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the transaction.| +| `originalTransactionID`
*String* | Id of the original sale transaction (EFTTransactionID)| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowobjects#3) (Customer reference, [Metadata](windowsobjects.md#metadata), [Money Remittance Options](windowsobjects.md#money-remittance-options),...). This object can be empty if no options are required.| + +**Code example** + +```csharp +//Initiate a refund for 10.00 in Great British Pounds +api.Refund(new BigInteger(1000),Currency.GBP,"00000000-0000-0000-0000-000000000000"); + + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); + +api.Refund(new BigInteger("1000"), Currency.EUR, map); +``` + +#### Events invoked +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry' +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 + +`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 but it also accepts a map with optional parameters. Note that transactions can only be reversed within the same day as the transaction was made. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `amount` Required
*BigInteger* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the transaction.| +| `originalTransactionID` Required
*String* | Id of the original refund transaction (EFTTransactionID)| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowobjects#3)| + + +**Code example** + +```csharp +//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*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry' +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 + +`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. 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* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required
*Currency* | Currency of the transaction.| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowobjects#3) (Customer reference, [Metadata](windowsobjects.md#metadata), [Money Remittance Options](windowsobjects.md#money-remittance-options),...). This object can be empty if no options are required.| + +**Code example** + +```csharp +// Basic MoTo Sale +this.Hapi.MotoSale(new BigInteger("1000"), Currency.EUR); + +// With options +Dictionary dic = new Dictionary(); +dic.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); + +this.Hapi.MotoSale(new BigInteger("1000"), Currency.EUR, dic); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 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. 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* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +| `currency` Required*Currency* | Currency of the transaction.| +| `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.| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowobjects#3) (Customer reference, [Metadata](windowsobjects.md#metadata), [Money Remittance Options](windowsobjects.md#money-remittance-options),...). This object can be empty if no options are required.| + +**Code example** + +```csharp +//Basic MoTo Refund +this.Hapi.MotoRefund(new BigInteger(1000), Currency.EUR); + +this.Hapi.MotoRefund(new BigInteger(1000), Currency.EUR, "00000000-0000-0000-0000-000000000000"); + + +//With Options +Dictionary dic = new Dictionary(); +dic.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.MoneyRemittanceCountryCode.Tag(), "USA"); +map.Add(XmlTag.MoneyRemittanceFullName.Tag(), "John Doe"); + +this.Hapi.MotoRefund(new BigInteger("1000"), Currency.EUR, dic); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 Reversal + +`moToReversal` Method + +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.| +| `map` *Map* | A map including optional transaction parameters| + +**Code example** + +```csharp +this.Hapi.MotoReversal("00000000-0000-0000-0000-000000000000"); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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 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
*BigInteger* | Transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP).| +|`currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the charge| +| `map` *Map* | A map including optional transaction parameters| + +**Code example** + +```csharp +this.Hapi.moToPreAuthorization(new BigInteger(1000), Currency.EUR); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); + +this.Hapi.moToPreAuthorization(new BigInteger(1000), Currency.EUR, map); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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.| + +## 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 +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)| + +**Code example** + +```csharp +// string validReceipt = '...'; +bool success = api.PrintReceipt(validReceipt); +``` + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the receipt was sent to the printer, false otherwise| + + +## Signature Result + +`SignatureResult` Method + +A signatureRequired event is invoked during a transaction when a signature verification is required, for example when a payment is done with a swiped or chip and signature card. The merchant is required to ask the cardholder for signature and approve (or decline) the transaction. signatureResult tells the payment terminal 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 payment terminal. Note that this event is only required for an HiLite integration and can be safely ignored for a PAX or Telpo integration. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `accepted` Required
*Boolean* | pass true if merchant accepts customer signature| + +**Code example** + +```csharp +//Receiving a SignatureRequest from the SDK. +public void SignatureRequired(SignatureRequest signatureRequest, Device device) +{ + //If you accept the signature + api.SignatureResult(true); +} +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully sent to the payment terminal| + + + +## Tip Adjustment + +`TipAdjustment` Method + +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. This functionality is limited to HiLite terminals. + +#### Parameters + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*String* | Id of the original sale transaction (EFTTransactionID) | + + +**Code example** + +```csharp +//Initiate a tip adjustment for $10.00 +Task result = hapi.TipAdjustment(BigInteger.Parse("1000"), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec"); +FinancialStatus status = result.Result; +if (status != FinancialStatus.FAILED) +{ + if (status == FinancialStatus.AUTHORISED) + { + //Success! + } + else + { + //Declined + } +} +``` + +**Returns** + +Result of the tip adjustment transaction, this is an asynchronous method that returns a task called ``, 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 + +`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 | +| ----------- | ----------- | +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3)| + +**Code example** + +```csharp +//Initiates a card tokenization operation. +api.TokenizeCard(); +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| [OperationStartResult](windowsobjects.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.| + + + +## Stop Current Transaction + +`StopCurrentTransaction` Method + +This method attempts to cancel the current transaction on the payment terminal. Note that operations can only be cancelled before requests are sent to the gateway. There is a flag called [cancelAllowed](windowobjects#status-info) in the currentTransactionStatus event that can be used to check if the transaction is in a state allowing the transaction to be cancelled. + + +**Code example** + +```csharp +this.Hapi.StopCurrentTransaction(); +``` + +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| `Boolean`| `true` if the operation was successfully sent to the payment terminal| + + +## 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*](windowsobjects.md#1) | Currency of the charge| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3)| + +**Code example** + +```csharp +// Basic +this.Hapi.PreAuthorization(new BigInteger("1000"), Currency.EUR); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); + +this.Hapi.PreAuthorization(new BigInteger("1000"), Currency.EUR, map); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](windowsobjects.md#OperationStartResul)*| 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 funds to be pre-authorized - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)| +| `currency` Required
[*Currency*](windowsobjects.md#1) | Currency of the charge| +| `originalTransactionID` Required
*String* | Transaction id of the original pre-auth transaction| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3)| + + +**Code example** + +```csharp +// Basic PreAuth Increase +this.Hapi.PreAuthorizationIncrease(new BigInteger("1000"), Currency.EUR, ""00000000-0000-0000-0000-000000000000"); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); + +this.Hapi.PreAuthorizationIncrease(new BigInteger("1000"), Currency.EUR, "00000000-0000-0000-0000-000000000000", map); + +// Basic PreAuth Decrease +this.Hapi.PreAuthorizationIncrease(new BigInteger("-1000"), Currency.EUR, ""00000000-0000-0000-0000-000000000000"); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](windowsobjects.md#OperationStartResul)*| 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*](windowsobjects.md#1) | Currency of the charge| +| `originalTransactionID` Required
*String* | Transaction id of the original pre-auth transaction| + +**Code example** + +```csharp +// Basic +this.Hapi.PreAuthorizationCapture(new BigInteger("1000"), Currency.EUR, "00000000-0000-0000-0000-000000000000"); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); + +this.Hapi.PreAuthorizationCapture(new BigInteger("1000"), Currency.EUR, "00000000-0000-0000-0000-000000000000", map); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](windowsobjects.md#OperationStartResul)*| 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 released 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](windowstransactions.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](windowsobjects.md#25) -> [AUTHORISED](windowsobjects.md#25)). + +**Parameters** + + +| Parameter | Notes | +| ----------- | ----------- | +| `originalTransactionID` Required
*String* |Transaction id of the original pre-auth or capture GUID transaction| +| `map`
*Map* | A map including [*optional transaction parameters.*](windowsobjects.md#3)| + +**Code example** + +```csharp +// Basic +this.Hapi.PreAuthorizationReversal("00000000-0000-0000-0000-000000000000"); + +// With options +Dictionary map = new Dictionary(); +map.Add(XmlTag.CustomerReference.Tag(), "YourCustomerReference"); +map.Add(XmlTag.Metadata1.Tag(), "Data 1"); + +this.Hapi.PreAuthorizationReversal("00000000-0000-0000-0000-000000000000", map); +``` +#### Events invoked + +**[*currentTransactionStatus*](windowsevents.md#4)** + +This event gets statuses from the payment terminal during the transaction, for example: 'waiting for card' or 'waiting for PIN entry'. +**** + +**[*signatureRequired*](windowsevents.md#5)** + +This event is invoked if the card issuer requires the cardholder to sign the transaction receipt. +**** + +**[*endOfTransaction*](windowsevents.md#6)** + +This event is invoked when the transaction is completed, it contains the transaction result and receipts. +**** + +**Returns** + +| Parameter | Notes | +| ----------- | ----------- | +| *[OperationStartResult](windowsobjects.md#OperationStartResul)*| 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/windows_versioned_sidebars/version-Windows SDK 4.4.0-sidebars.json b/windows_versioned_sidebars/version-Windows SDK 4.4.0-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/windows_versioned_sidebars/version-Windows SDK 4.4.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/windows_versions.json b/windows_versions.json index 7b8e0b2..3137b3c 100644 --- a/windows_versions.json +++ b/windows_versions.json @@ -1,4 +1,5 @@ [ + "Windows SDK 4.4.0", "Windows SDK 4.3.1", "Windows SDK 4.2.0", "Windows SDK 4.1.0",