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:
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.
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
Pre-requisite: request your test credentials (API key) and a payment terminal from Handpoint.
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?"
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 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 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.
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 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} 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.
