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.

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 a custom header ( "AUTH_TOKEN").

Configuration

Endpoints

Initialize

method Available since 1.0.0

Initialize

Initializes the REST API client and returns the list of payment terminals associated with the merchant account

Parameters

Parameter	Notes
`API_key ` string*	The Actor API key.

Returns

Devices: List of Device objects

Code example

Operation executed using CLI tool CURL:
REQUEST:
  curl -X GET \
   -H "ApiKeyCLoud: MeRcHaNt-ApIkEy" \
   "https://cloud.handpoint.com/initialize"

RESPONSE:
 Code 200 -> Body: 
  [
    {
      "merchant_id_alpha": "merchantID",
      "serial_number": "082104578",
      "ssk": "01020304050607080910111213141516",
      "terminal_type": "PAXA920"
    }  
  ]

Transactions

method Available since 1.0.0

Transactions

POST endpoint used to execute a financial operation

Parameters

Parameter	Notes
`Header: ApiKeyCloud ` string*	Request Header used to identify the merchant
`Request Body: Transaction Request ` TransactionRequest*	Object containing the transaction information

Returns

Transaction Accepted: Response code 202 is received if the transaction has been successfully sent to the terminal and the Transaction Response has been received by the callbackUrl.
BadGateway Response: Response code 502 can be received for multiple reasons, make sure the API key is correct, if so, contact the Handpoint support team.
ServiceUnavailable Response: Response code 503 is received when the terminal is offline or the connection is unstable. Review the connection state of the terminal and retry the transaction.
GatewayTimeout Response: Response code 504 is received when no ack is sent back from the terminal, usually due to an unstable connection. Check the network connection of the terminal and retry the transaction if no transaction result was received by the callback endpoint.

Code example

Operation executed using CLI tool CURL:
REQUEST:
  curl -X POST \
   -H "ApiKeyCLoud: MeRcHaNt-ApIkEy" \
   -H "Content-Type: application/json" \
   -d '{
        "operation":"sale",
        "amount":"10000",
        "currency":"EUR",
        "terminal_type":"PAXA920",
        "serial_number":"1547854757",
        "ssk":"10203040506070809101112131415",
        "callbackUrl":"https://url.where.the.result.is.served.com",
        "token":"123456789"
        }' \
  "https://cloud.handpoint.com/transactions"

RESPONSE:
 Code 202 -> Body: {"statusMessage":"Transaction accepted"}

Objects

Status

enum Available since 1.0.0

Status

An enum containing information about the status of the transaction.

Possible values

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 Undefined InitialisationComplete

Transaction Request Object

object Available since 1.0.0

TransactionRequest

An object to store the information about the payment terminal you are working with. ALL values are REQUIRED

Properties

Property	Description
`operation` OperationType	The type of transaction to be performed.
`serial_number` String	Device serial number
`terminal_type` String	Device type
`ssk` String	Device shared secret key to authorize the operations.
`callbackUrl` String	Url where the device will serve the Transaction Result
`token` String	Token used to authenticate the device when serving the result in the callbackUrl . The token will be injected in the Request Header with key value 'AUTH_TOKEN'.
`amount` String	Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 EUR). REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard.
`currency` Currency	The currency of the transaction. REQUIRED for operations: sale, refund, refundReversal, saleReversal and saleAndTokenizeCard.
`originalTransactionId` String	The transaction id of the original transaction to reverse. REQUIRED for operations: refundReversal and saleReversal.
`receipt` String	HTML receipt or url to locate the receipt, it can be found in the response of a Transaction Request, in the fields merchantReceipt or customerReceipt

Code example

{
       "operation": "sale",
       "amount": "10000",
       "currency": "EUR",
       "terminal_type": "PAXA920",
       "serial_number": "1547854757",
       "ssk": "10203040506070809101112131415",
       "callbackUrl": "https://url.where.the.result.is.served.com",
       "token": "123456789"
}

Transaction Result Object

object Available since 1.0.0

TransactionResult

The response object is sent back from the payment terminal to your application and contains the transaction result. It is formatted in JSON and structured as a collection of "name":"value" pairs. Values are always a string except in the cases where the value is a boolean or another collection of "name":object pairs.

Properties

Property	Description
`authorisationCode` String	The transaction authorization code, as given by the system.
`budgetNumber` String	The budget number can be used to split payments over several months.
`cardEntryType` CardEntryType	The card data acquisition type.
`cardSchemeName` String	The card, reported, scheme name.
`cardToken` String	Gets the card token if it's available, null otherwise.
`cardTypeId` String	The card type id is an identifier inside the Handpoint gateway which represents what kind of card was used.
`chipTransactionReport` String	If present, a full EMV report by the card reader on the Card and Terminal involved in the transaction.
`currency` Currency	The currency code used for the transaction.
`customerReceipt` String	Customer receipt of transaction from card reader in html format.
`customerReference` String	echo of the optional customerReference parameter sent in the transaction request.
`deviceStatus` DeviceStatus	The status of the payment terminal
`dueAmount` String	If there's still a part of the amount to be paid.
`eFTTimestamp` String	The date and time of the transaction, in ISO format (YYYYMMDDHHmmSS).
`eFTTransactionID` String	The EFT reference, given by the system, to make the transaction unique.
`errorMessage` String	Description of the error, if any.
`ExpiryDateMMYY` String	The expiry date of the card used for the operation.
`finStatus` FinancialStatus	The result of the transaction.
`gratuityAmount` String	The gratuity amount entered by the cardholder, if any.
`gratuityPercentage` String	The gratuity amount, as a percentage of the requested amount.
`isRecoveredTransaction` boolean	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.
`maskedCardNumber` String	The masked card number used in the operation.
`merchantReceipt` String	Merchant receipt of transaction from card reader in html format.
`originalEFTTransactionID` String	The original EFT reference, given by the POS, as part of a VOID_SALE or a VOID_REFUND transaction.
`requestedAmount` String	The amount requested by the point of sale (POS), as requested by the POS (i.e. no decimal point).
`statusMessage` String	A human readable description for the returned Status.
`totalAmount` String	The total of the gratuity and requested amount.
`transactionID` String	The transaction number used for this transaction, as maintained by the electronic fund transfer (EFT) Client.
`type` TransactionType	The type of financial transaction performed.
`verificationMethod` VerificationMethod	The cardholder verification method (CVM).

Code example

{
  "authorisationCode":"",
  "budgetNumber":"",
  "cardEntryType":"MSR",
  "cardSchemeName":"UNKNOWN",
  "cardToken":"",
  "cardTypeId":"************9991",
  "chipTransactionReport":"",
  "currency":"USD",
  "customerReceipt":"https://s3.amazonaws.com/expressapp/1590053534499/customer/efa35950-9b45-11ea-817c-9710c9fdf18a.html",
  "customerReference":"",
  "deviceStatus": {
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "08210378549",
    "statusMessage": "Successful"
  },
  "dueAmount":0,
  "errorMessage":"",
  "expiryDateMMYY":"1249",
  "finStatus":"AUTHORISED",
  "gratuityAmount":0,
  "gratuityPercentage":0,
  "maskedCardNumber":"************9991",
  "merchantReceipt":"https://s3.amazonaws.com/expressapp/1590053535052/merchant/efa35950-9b45-11ea-817c-9710c9fdf18a.html",
  "originalEFTTransactionID":"",
  "requestedAmount":0,
  "statusMessage":"Successful",
  "totalAmount":1000,
  "transactionID":"efa35950-9b45-11ea-817c-9710c9fdf18a",
  "type":"SALE",
  "verificationMethod":"UNDEFINED",
  "efttimestamp":1590053533055,
  "efttransactionID":"efa35950-9b45-11ea-817c-9710c9fdf18a",
  "recoveredTransaction":false
}

Code example

{
       "merchant_id_alpha": "Test_Merchant",
       "serial_number": "614004878",
       "ssk": "74817EA5C63437ADE7AA3A5401",
       "terminal_type": "PAXA920",
}

Currency

enum Available since 1.0.0

Currency

An enum of most currencies in the world.

Contains the ISO name, ISO number and the name of the currency. Additionally contains 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 Status

object Available since 1.0.0

DeviceStatus

A class that holds the device status.

Properties

Property	Description
`SerialNumber` String	The serial number of the device
`BatteryStatus` String	The battery status in percentages of a device
`BatterymV` String	The battery milli volts of a device
`BatteryCharging` String	The battery charging status of a device
`ExternalPower` String	The status of an external power of a device
`ApplicationName` String	The application name used on a device
`ApplicationVersion` String	The application version number used on a device
`bluetoothName` String	The bluetooth interface name used on a device
`statusMessage` String	Device human readable status message

Code example

{
    "applicationName": "TestApp",
    "applicationVersion": "20.1.0.1",
    "batteryCharging": "Charging",
    "batteryStatus": "100",
    "batterymV": "4134",
    "bluetoothName": "A920",
    "externalPower": "USB",
    "serialNumber": "0821032397",
    "statusMessage": "Card reader time out"
}

Transaction Type

enum Available since 1.0.0

TransactionType

An enum representing different types of transactions.

Possible values

UNDEFINED SALE VOID_SALE REFUND VOID_REFUND CANCEL_SALE CANCEL_REFUND TOKENIZE_CARD