Handpoint API

Handpoint is a P2PE-encrypted terminal cloud. Merchant software hits our REST API to tell a terminal to take a sale; the terminal runs the EMV / contactless / swipe flow and returns the result.

Three independent APIs ship under the Handpoint umbrella, each with its own auth and its own base URL:

• REST API – taking payments on physical terminals.
• TMS API – onboarding merchants, assigning terminals, minting API keys.
• Transaction Feed API – pulling transactions for reporting / dashboards.

Two ways to drive a Handpoint terminal directly:

• Cloud API (REST). Your server POSTs to a PAX terminal in Integrated (cloud) mode, then polls for the result or receives a callback. Auth: ApiKeyCloud header with a merchant Cloud key. A merchant can have several keys.
• SDKs. Android SDK on PAX, Android / iOS for HiLite over Bluetooth, JavaScript SDK (through Cloud), Windows .NET, Cordova / Ionic. SDKs use the merchant’s SSK (one per merchant; GET /devices returns it).

• The .io hosts serve debug / staging devices and DEMO merchants only. Credentials do not work across .io and .com.
• /status lives only on transactions.*; it returns 404 on cloud.*.
• Amounts. Cloud and SDK operations take minor units as strings ("1000" = 10.00). Back-office endpoints (/reversal, /moto/*, /preauthorization/*, tip adjustment) take major units ("95.00").
• Device names are serialNumber-terminalType.

Each surface uses a different credential and a different header:

• REST API – ApiKeyCloud header. The key is unique per merchant; you mint it through the TMS API.
• TMS API – JWT obtained from a Login endpoint, passed in Authorization: Bearer on subsequent calls.
• Transaction Feed API – AnalyticsApiKey header. Separate key from the REST API.

Pick the base URL by terminal type, not by where your code is running. Production / demo terminals hit cloud.handpoint.com; debug terminals hit cloud.handpoint.io. Demo terminals use a mock acquirer – no funds move, but every other behavior is real.

The .io hosts serve debug devices and DEMO merchants only. Credentials minted on one side do not work on the other. See Integration paths & hosts.

Every transaction request returns 202 Accepted with a transactionResultId – the terminal hasn’t actually run the transaction yet. You get the real result one of two ways:

• Push (4.1) – supply callbackUrl + token in the request. Handpoint POSTs the result to your URL when the terminal finishes; the token echoes in AUTH-TOKEN so you can authenticate the callback. Your callback URL must accept a certificate authority Android 5-10 supports (terminal OS versions).
• Poll (4.2) – omit those fields. GET /transaction-result/{id} with the returned id. Returns 204 while in flight, 200 with the result when done.

Send callbackUrl and token on the POST. When the terminal finishes, Handpoint POSTs the TransactionResult to your URL with the token in the auth-token header (it may arrive as AUTH-TOKEN; compare case-insensitively).

• Use a fresh UUID as the token for every transaction and reject callbacks whose header does not match.
• Retries: every 5 s for 100 s, then exponential backoff capped at 15 min, for up to 2 days. Any 2xx stops them.
• recoveredTransaction: true marks a redelivery. Dedupe on transactionReference.
• Return 200 even for UNDEFINED (keep resolving it through recovery).
• The callback host’s TLS certificate must chain to a common CA (DigiCert, GlobalSign, Sectigo); terminal OS trust stores are limited.

Retrieves every payment terminal (and Virtual Terminal) associated with the merchant. Use the returned serial_number + terminal_type on every subsequent transaction request.

Sends an operation to the terminal. Valid operation values include sale, refund, refundReversal, preAuthorizationCapture, and more.

amount is in minor units (cents) as a string: "10000" = €100.00. transactionReference must be a UUID v4 for original operations; linked operations (refund, reversal) pass originalTransactionId instead.

Common error codes: 1001 device busy, 1002 device offline / not responding, 1003 cancel operation not allowed.

Polling endpoint for flow model 4.2. Hit it until you get a 200. Returns the full transaction-result object with masked PAN, card scheme, AVS / CVV results, signature URL, customer + merchant receipt text, and the cardToken you can re-use for MOTO calls within 12 months.

Query by the transactionReference you supplied on the original request. Useful when you’ve lost the transactionResultId or when you need to find every linked operation (refunds, reversals, captures) tied to one original sale – pass selector=all.

Lives on a different host: transactions.handpoint.com / .io.

finStatus values: IN_PROGRESS, UNDEFINED, PARTIAL_APPROVAL, AUTHORISED, DECLINED, CANCELLED, FAILED, PROCESSED, REFUNDED, CAPTURED. Which are final, timing, and retry rules: Transaction recovery.

Persist a UUID v4 transactionReference before you send, then resolve the outcome by result id (terminal channel) or by reference (status host). GET /transactions/{ref}/status returns the first operation for the reference; /status/{all|first|last|n} selects others. Each entry carries type, finStatus, totalAmount, transactionID, and transactionReference or originalEFTTransactionID. Net = AUTHORISED sales minus refunds and reversals; a later operation’s finStatus reflects its state when it was processed.

Timing

• Poll GET /transaction-result/{id} every 3 to 5 s (204 in progress, 200 result, 404 unknown). Card-present typically takes 10 to 30 s.
• Worst case is about 340 s. Use an active-recovery timeout of 360 s from the send, then query /status once more. Still IN_PROGRESS or UNDEFINED: flag for manual reconciliation.
• Never auto-retry with the same reference. A retry is a new operation with a new UUID, and only after a final non-charged status.

Two-thread variant

• Thread 1 polls the terminal channel every 5 s (authoritative). Thread 2 polls /status every 10 s.
• If /status says AUTHORISED and no terminal result has arrived, send pingDevice (expect PING_PONG).
• After 300 s /status is provisional. If it says AUTHORISED and no terminal result ever came, reverse the sale.

Reference rules

• Send transactionReference only on originals: sale, unlinked refund, saleAndTokenizeCard, preAuthorization. Not on reversal, linked refund, capture / void or tip adjust.
• customerReference is an echo only. Duplicate protection is duplicate_check (default true).
• KI-2026-008 (CUS-837): moToSale ignores transactionReference. Poll by transactionResultId and store transactionID.

Terminal-initiated reversals

The terminal can reverse an approved sale itself. The result comes back finStatus: CANCELLED with customFields.messageReasonCode 4000 plus a cause code in another custom field (Handpoint does not document that field’s name; match on the code values below). Do not retry and do not send a reversal.

Adjust the tip amount on an already-authorized sale before batch settlement. US restaurants only; TSYS / VANTIV acquirers only. amount is in major units (dollars) – note the mismatch with the transaction amount field which is in minor units.

EPI (TSYS): send it before the EPI batch auto-close (about 11pm EST); 0 voids the tip. Errors ORIGINAL_NOT_FOUND, BATCH_ALREADY_CLOSED, TIP_ADJUSTMENT_NOT_ENABLED, AMOUNT_EXCEEDS_LIMIT. See EPI acquirer features.

Retrieve a card token from a completed card-present transaction so you can charge the same card via the MOTO endpoints later. Eligible transaction types: sale, refund, preAuthorizationCapture, moToSale, moToRefund. Must be requested within 12 months of the original transaction.

Modify the authorized amount on an open pre-authorization without re-running the card. increaseAmount is the delta in major units. Pass subtract: "1" to decrease.

Finalize an open pre-auth and actually charge the card. capturedAmount is in major units; can’t exceed the authorized amount (after any increases). Add a tip via tipAmount.

Charge a previously-tokenized card without involving a terminal. cardToken comes from a prior card-present sale (or the deferred-tokenization endpoint). amount in major units.

moToSale without a cardToken shows the terminal’s manual entry screen. Optional channel MO or TO. AVS: send enableAvsFields: true (the terminal asks) or a billing object (zipCode required, address optional). Needs the merchant flags motoEnabled (and avsForMoto for AVS) in TMS; otherwise MOTO_NOT_ENABLED. moToRefund is the keyed refund.

Handpoint has no per-sale switch that shows or hides a keyed option on a normal sale; keyed entry is its own operation. KI-2026-008: poll moToSale by transactionResultId.

Refund a prior MOTO sale (linked by originalGuid). Amount can’t exceed the original; currency must match.

Void a previous MOTO sale within the reversal window. Deprecated by Handpoint: use POST /reversal.

Reverse a sale without the terminal. originalGuid is the sale’s transactionID; amount (major units) is optional and makes it a partial reversal where the acquirer supports it. messageReasonCode: CUSTOMER_CANCELLATION (default) or TIMEOUT_WAITING_FOR_RESPONSE. The call is synchronous. /moto/reversal is deprecated; use /reversal.

Errors: 3158 not found, 3051 already reversed, 4066 partial amount exceeds the original. On-device reversal is saleReversal with originalTransactionId, same business day.

Three related endpoints, all POST, all take { deviceType, serialNumber, batchNumber } in the body:

All three are Beta and depend on the underlying acquirer supporting them.

Administrative commands for a terminal. Every endpoint returns 202 Accepted when the command is queued. Requires the Handpoint Payments App 4.6.0+ in Integrated mode (or SDK 7.1006.0+). Common error: 400 DeviceNotListening means the terminal isn’t connected right now.

Other POS levers on POST /transactions: stopCurrentTransaction, pingDevice, printReceipt, bypassOptions, tipConfiguration.headerName / footer, a preset tipAmount, and moToSale without a card token (keyed screen). Not available from Handpoint: idle-screen branding or logos, hiding the cancel key, a per-sale keyed option on a normal sale, and pushing customer-display messages.

What Handpoint supports when EPI is the acquirer (TSYS). Merchant flags (MOTO, AVS for MOTO, partial reversal, tip adjust, batch) are server-side TMS settings.

Sale fields (Cloud)

amount, currency, terminal_type, serial_number, customerReference, transactionReference, callbackUrl, token, taxInformation, purchaseOrderNumber, duplicate_check, bypassOptions {signatureBypass, pinBypass}, tipConfiguration, merchantAuth, metadata, moneyRemittanceOptions, billing.

For merchants whose acquirer on Handpoint is Paysafe. Paysafe merchants integrate with Handpoint directly; they are not on Merchant360.

Tokens

• PAYSAFE: tokenizeCard / saleAndTokenizeCard return cardTokenProvider: "PAYSAFE", a single-use token that lives about 15 minutes, for Paysafe’s Customer Vault. It does not work with Handpoint MOTO. Needs Paysafe onboarding.
• TOKENEX: cardTokenProvider: "TOKENEX", for loyalty and card matching only. No detokenize, no MOTO.

Interac

• Interac routes to TNS; other cards to TSYS. Batch close is TSYS only.
• Interac supports sale, sale with tip (the tip is folded into the total) and VOID only.
• VOID = Cloud refund with originalTransactionId, currency: "CAD", no transactionReference. Card present, same day, full amount. Label the button “VOID” in your UI.
• No remote reversal or refund, pre-auth, tip adjust or keyed entry for Interac.
• Errors: CARD_NOT_PRESENT, ALREADY_SETTLED, ORIGINAL_NOT_FOUND.

Refunds in the Paysafe Portal are card-not-present and outside Handpoint; after 24 h they use the eftTransactionID as MerchantRefNum.

Login returns a JSON Web Token. Send it in the Authorization: Bearer … header on every other TMS call. Tokens have a fixed lifetime – handle re-login when calls return 401.

Merchant lifecycle. The POST /merchants body must match your partner configuration (ISV id, acquirer id, etc.) – ask your Handpoint contact for the exact shape.

GET /merchants/{id} returns the merchant’s shared secret and other auth-grade fields; treat the response like a credential. After PUT, re-publish each assigned terminal’s configuration (see Lifecycle below).

Each terminal lives in one of two states: unassigned (in the pool, no merchant) or assigned (attached to exactly one merchant). Reassignment is unassign → assign.

You must call POST /publish after every assign / unassign / merchant-edit. Without it the Handpoint Gateway doesn’t know about the change and the terminal will keep authorizing under the old merchant context.

Cloud API keys are minted per merchant from the TMS. The POST response includes the unmasked key – that’s the only time you’ll see it. Store it server-side before handing to the merchant.

Standard onboarding for a new merchant + first terminal is six API calls in sequence:

• Login → JWT.
• Create the merchant.
• Add the terminal to the unassigned pool.
• Assign the terminal to the merchant.
• Publish the terminal config to the Gateway.
• Mint the merchant’s REST API key.

Different credential from the REST API. The Transaction Feed is a read-only reporting surface; the key here doesn’t let you take payments. Ask Handpoint to provision a separate Analytics key – don’t reuse the Cloud API key.

Date format is a single string of digits: YYYYMMDDhhmmss. 20260609143200 = June 9, 2026 at 14:32:00. Both startDate and endDate are required on every POST.

Five basic lookups, two type-filters (payouts = income, refundsandreversals = outflow), plus admin variants scoped to a specific merchant or to the partner level.

Every endpoint is POST so the body can carry the date range. The path parameters (guid, customerReference, partnerIdAlpha, merchantIdAlpha) sit in the URL.

Five aggregation families. {field} is the JSON attribute you’re aggregating over (amount, serialNumber, cardType, etc.). Net is a built-in convenience: payouts minus refunds+reversals.

Add /group/ to the path and supply three query params:

Same shape as /group/ but the response is pre-bucketed for charting libraries (timestamps on the X axis, the aggregate on Y). Skip the per-row mapping you’d normally do for a graph.