Handpoint documentation

Introduction

Introducing the Revolutionary Handpoint REST API: Seamlessly integrate card present payments into any software

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 card data. It is seamless to integrate, keeps all card data out of your system, 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. You even get a list of terminals to which you can connect. 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 P2PE transaction with the payment terminal, minimizing hassle for you and maximizing reliability, security, and control.

Release Notes

API Overview

First of all, ensure you are using the correct environment by checking if your terminal is a production terminal or a debug terminal, see "How to identify between a debug and production terminal?".
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) Send a POST transaction request to the REST API.
2) The API will validate the request body and, if it is correct, will respond back to your software with the response code 202 ("Accepted”) to confirm that the data has been correctly forwarded to the payment terminal.
3) The validated transaction request object is forwarded to the terminal and the transaction starts.
4.1) In case the original transaction request contains a callbackUrl and token, the transaction result will be sent back from the terminal to your software by using the callbackUrl. The terminal will be authenticated against your endpoint by setting the authentication token of the transaction request in the custom header ( "AUTH-TOKEN"). All 2XXs http response codes from the callbackUrl are considered as valid by the terminal to acknowledge of a successful delivery of the transaction result.
4.2) IMPORTANT Feature only compatible with Handpoint App v3.3.0 and above. In case the original transaction request does not ontain a callbackUrl and token, the transaction result is sent back from the terminal to Handpoint's REST-API. The result can then be retrieved from the endpoint GET https://cloud.handpoint.[com//io]/transaction-result/{transactionResultId} where the transactionResultId (also called cloud transaction identifier) is found in the answer from the initial POST[1] to the REST-API (see step 2)).

Downloads

Here is a Postman collection to get started with the REST API integration. In the collection there are different operations that can be performed such as Initialize, Ping device, Sale, Sale and tokenize, Sale reversal, Sale with partial approval, Refund, Refund reversal, Print receipt, Tokenize card and Update.

Get the Postman Collection!

Postman Collection

Configuration

Sandbox

Get started today with our sandbox. You can generate sample transactions and test the experience right in your browser. Check it at: http://www.handpoint.com/lab/cloudpos. A payment terminal is required to start testing.

This is the initial setup screen:

To get started, select the target environment where you are going to operate (Sandbox/Production). If the user has any doubts selecting the correct environment, click on "*How do I know what type of card reader do I have?" and you will be redirected to an explanation page.