Skip to main content

Build with AI agents

Handpoint provides machine-readable resources so AI coding agents (Claude Code, Codex, Cursor, and others) can generate accurate payment integrations without hallucinating API fields, acquirer constraints, or unsupported capability combinations.

Quick start for agents​

1. Fetch https://developer.handpoint.com/llms.txt for the full machine-readable reference:
   acquirer × feature support matrix, per-path code examples, and all reference page URLs.

2. Load the handpoint skill before writing any integration code:
   https://developer.handpoint.com/.well-known/skills/handpoint.md

3. Load a task-specific skill for the operation you are implementing.

Machine-readable reference — llms.txt​

/llms.txt contains:

  • The complete acquirer × feature support matrix (which acquirer supports which capability on which integration path)
  • Per-path code guidance (Cloud API, Android PAX, Android HiLite, iOS, Cordova, Back Office)
  • All reference page URLs

Fetch it at the start of any Handpoint integration task.

Agent skills​

Task-focused skill files provide precise, condensed guidance for specific integration tasks. Load only the skills relevant to your task.

The skills index is at /.well-known/skills/index.json.

SkillWhen to load
handpointAlways — load first. Global context, architecture overview, and which path and acquirer skill to load next.
paths/cloud-apiImplementing a REST API sale (any language, commands PAX terminal via Handpoint Cloud)
paths/android-paxBuilding an Android app that runs on-device on a PAX SmartPOS terminal
paths/android-hiliteBuilding an Android app paired with a HiLite Bluetooth reader
paths/ios-hiliteBuilding an iOS app paired with a HiLite Bluetooth reader
acquirers/epiEPI (North America) — batch close schedule, tip adjustment, pre-auth support
acquirers/paysafePaysafe (North America) — supported operations and constraints
acquirers/emerchantpayEmerchantPay (Europe) — tip-in-sale, pre-auth, supported operations
acquirers/paystraxPaystrax (Europe) — tip-in-sale, pre-auth, supported operations
optional/back-officeBack-office operations — reversals, refunds, pre-auth capture, MOTO
optional/transaction-feedTransaction reporting, reconciliation, and result recovery

Integration paths — quick reference​

What you're buildingPathHardware
Server controls PAX terminal via HTTP (any language)Cloud API (REST)PAX SmartPOS
Android app running on the PAX terminal itselfAndroid SDK (PAX)PAX SmartPOS
Android or iOS app paired with a portable card readerAndroid / iOS SDK (HiLite)HiLite Bluetooth
Server-side operations without a terminalBack Office REST APINone
EU online checkoutSmartBoardNone

Common agent mistakes to avoid​

  • Do not assume all acquirers support the same features. EPI requires daily batch close; PAYSAFE does not support remote sale or pre-authorization; EmerchantPay/Paystrax include tipAmount in the sale, not post-sale. Always load acquirer-selection first.
  • Do not retry UNDEFINED transactions. finStatus: UNDEFINED means the result is unknown — retrying may double-charge. Use the Transaction Feed API to recover.
  • The header is ApiKeyCloud, not Authorization or Api-Key.
  • Amounts are in minor currency units. 1000 = $10.00, not $1000.
  • Reversals are synchronous; sales and refunds are asynchronous. Poll for sales and refunds; reversal response is immediate.

Full documentation​