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



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.

Processing Payments Simulation

Test transactions are conducted against a test server which is designed to simulate the behavior of an acquiring bank without moving any funds. As with every Handpoint terminal, sensitive card data is fully encrypted.

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
Any other values will behave as normal authorized operations.

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
Header: ApiKeyCloud *
string		 Request Header used to identify the merchant


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.1

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 Result has been received by the callbackUrl. In case of pingDevice Operation no result will be delivered to the callbackUrl (not required for this operation), a 202 code will be returned to mark the device as online
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.1

TransactionRequest

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

Properties

Property Description
operation
OperationType		 The type of transaction to be performed. REQUIRED
serial_number
String		 Device serial number. REQUIRED
terminal_type
String		 Device type. REQUIRED
ssk
String		 Device shared secret key to authorize the operations.
callbackUrl
String		 Url where the device will serve the Transaction Result. REQUIRED for operations: sale, refund, refundReversal, saleReversal, saleAndTokenizeCard, tokenizeCard, printReceipt, update and cardPan
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'. REQUIRED for operations: sale, refund, refundReversal, saleReversal, saleAndTokenizeCard, tokenizeCard, printReceipt, update and cardPan
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. REQUIRED for operations: printReceipt.

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
}

Verification Method

enum Available since 1.0.0

VerificationMethod

An enum representing the possible verification methods used during the transaction.

Possible values

UNDEFINED SIGNATURE PIN PIN_SIGNATURE FAILED NOT_REQUIRED

Card Entry Type

enum Available since 1.0.0

CardEntryType

An enum representing different card entry types.

Possible values

UNDEFINED MSR ICC CNP

Operation Type

enum Available since 1.0.1

OperationType

An enum representing different types of transactions.

Possible values

sale refund refundReversal saleReversal saleAndTokenizeCard tokenizeCard printReceipt update cardPan pingDevice

Financial Status

enum Available since 1.0.0

FinancialStatus

An enum representing different statuses of a finalized transaction

Possible values

UNDEFINED AUTHORISED DECLINED PROCESSED FAILED CANCELLED PARTIAL_APPROVAL

Device

object Available since 1.0.0

Device

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

Properties

Property Description
merchant_id_alpha
String		 Merchant unique identifier to which the device is associated
serial_number
String		 Device serial number
ssk
String		 Device shared secret key to authorize the operations.
terminal_type
String		 Device type

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 CARD_PAN