You are currently viewing the documentation for version

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.

API Overview

First of all, ensure you are using the correct environment by reviewing the type of card reader you have. To check if you should be using a production or development environment, see "How do I know what type of card reader do I have?" and select the corresponding URL, as you see below:
   Production: https://cloud.handpoint.com/...
   Development: 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 (containing the Transaction Request) and, if it is correct, it will respond back to your software with the response code 202 ("Accepted”) to confirm that the data has been correctly forwarded to the card reader.
3) The validated Transaction Request object is forwarded to the terminal and the transaction starts.
4) The Transaction Result is sent back from the terminal to your software by using the callbackUrl from the Transaction Request. The terminal will be authenticated against your endpoint by setting the authentication token of the Transaction Request in custom header ( "AUTH-TOKEN"). All 2XXs http response codes from the callbackUrl are valid to notify the device of a successful delivery of the result.



Configuration

Just request a valid API key from Handpoint to start using API. Initialize your interface with the API key and receive the list of devices available to perform a financial operation. Fast and easy.

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. Our sandbox couples as a terminal simulator and makes it simple for you to start testing right away, even if you don’t yet have a terminal available.

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.