Restaurant payments

Restaurants have more moving parts than a standard retail checkout: tabs that stay open across a meal, tips that may be entered after the guest leaves, and staff who need to move around the room without returning to a counter terminal. This guide covers the Handpoint features that match those workflows.

---

Integration path: counter POS or tableside all-in-one

	Cloud API + PAX terminal	Android SDK on PAX
Where your software runs	Your server, any language	On the PAX terminal itself
Physical setup	Counter POS with terminal alongside	One device: terminal is the POS
Tip adjustment	Yes — back-office API call	Yes — back-office API call
Pre-auth (tab)	Yes	Yes
Best for	Existing POS software, web-based systems	Tableside ordering, all-in-one builds

If your POS is a server-side application (Python, PHP, Node.js, .NET), use the Cloud API — see Cloud API Integration Guide. If you're building an application that lives on the PAX terminal itself, embed the Android SDK — see Android SDK (PAX) Integration Guide.

---

Pre-authorization for tabs

Use pre-authorization when a guest opens a tab and the final amount is unknown. The card is authorized for an estimated hold at the start; you capture the actual total — including tip — when the tab closes.

Lifecycle:

1. Open tab — guest presents card; a preAuthorization creates a hold. Card-present, requires terminal.
2. Close tab — when the bill is ready, capture from your server with the final amount. Back-office, no terminal required.
3. Walk-away tab — if the guest leaves without closing, release the hold with a preAuthorizationReversal.

# Step 1 — Open tab (card-present)
POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "preAuthorization",
  "amount": "5000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "3c9de220-b14a-4a0c-9d2e-b3c1088e5a91"
}

# Step 2 — Capture at tab close (back-office, no terminal)
POST https://cloud.handpoint.com/preauthorization/capture
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "originalGuid": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "capturedAmount": "4700",
  "tipAmount": "800"
}

originalGuid is the transactionID from the pre-auth result. Always capture or reverse before the hold expires — card networks release holds in 7–30 days depending on the issuer.

Acquirer support

Pre-auth is available on EPI, EmerchantPay, and Paystrax. See Pre-Authorization Guide for the full lifecycle including increase/decrease and capture reversal.

---

info

For the complete tip strategy reference — acquirer support, mutual exclusivity rules, and how to undo a tip adjustment — see the Tipping Guide.

Tip collection: two approaches

Sale with Tip — guest selects at the terminal

The tip prompt is part of the checkout flow. The terminal presents percentage and custom tip options before the card is processed. The total (base + tip) is authorized in a single step.

Use this when guests pay at a counter or handheld where they interact with the terminal directly.

{
  "operation": "sale",
  "amount": "3800",
  "currency": "USD",
  "tipConfiguration": {
    "baseAmount": "3800",
    "tipPercentages": [15, 18, 20],
    "enterAmountEnabled": true,
    "skipEnabled": true,
    "footer": "Thank you!"
  }
}

Tip Adjustment — server enters tip from a paper receipt

The sale closes at the base amount. After the guest leaves, the server enters the tip from the signed receipt and your system posts a back-office call before settlement.

POST https://cloud.handpoint.com/transactions/e6254050-65ab-11f1-a9af-ffa530c6e21f/tip-adjustment
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "tipAmount": 800,
  "currency": "USD"
}

The path parameter (e6254050-…) is the transactionID from the original AUTHORISED sale result.

Before batch close only

Tip adjustments submitted after batch close are not applied. If you use EPI or PAYSAFE, automate the batch close at a fixed overnight time and enforce a cut-off window for tip entry.

Acquirer support

Tip Adjustment is supported on EPI and PAYSAFE (credit/debit cards only — not Interac). For EU merchants on EmerchantPay or Paystrax, use Sale with Tip or pre-auth capture with tipAmount instead.

---

End-of-day: batch close

EPI merchants need a batch close to trigger settlement. PAYSAFE settles automatically — no batch close required. Send this at end of service or on a scheduled overnight job:

POST https://cloud.handpoint.com/batch/close
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "terminal_type": "PAXA920",
  "serial_number": "082104578"
}

After batch close, same-day reversals are no longer possible — use a Refund instead. Tip adjustments submitted after batch close are silently dropped.

EmerchantPay and Paystrax settle automatically — no batch close required.