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.

Integration paths — quick reference​

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.
• Amount units differ by endpoint — see Cloud API code-generation facts below.
• Reversals are synchronous; sales and refunds are asynchronous. Poll for sales and refunds; reversal response is immediate.
• Determine the acquirer and integration path before generating implementation code — not all features are supported by all acquirers, and SDK methods differ per integration path.

Merchant vertical → integration path​

Integration paths are not mutually exclusive. A single ISV can implement multiple paths under one Handpoint account. Example: Cloud API at the counter + Android HiLite for field staff + back-office MOTO for phone orders — all sharing the same merchant credentials and transaction feed.

Back-office operations are always available regardless of integration path. Tip adjustment, reversal, refund, MOTO, pre-auth capture, and deferred tokenization are server-side REST calls that work alongside any card-present integration. Subject to acquirer support — see your acquirer's page for per-feature availability: EPI · PAYSAFE · EmerchantPay · Paystrax.

Cloud API code-generation facts​

Common sources of incorrect code.

Amount units differ by endpoint:

• POST /transactions → amount is minor units as a string (digits only, no decimal) — "1000" = $10.00
• POST /moto/sale, POST /moto/refund, POST /reversal → amount is major-unit decimal — "10.00" = $10.00
• Do not use the same amount-formatting logic for both endpoint families.

finStatus — complete enum (use this to generate exhaustive switch/match blocks):

IN_PROGRESS   → not final, keep polling
UNDEFINED     → not final, run recovery flow before retrying
AUTHORISED    → final, approved
DECLINED      → final, declined — do not retry without cardholder action
FAILED        → final, technical failure — run recovery flow before retrying
PARTIAL_APPROVAL → NOT final — terminal showing accept/decline prompt (US only); continue polling for 60s+ or until final transaction-result; can change to CANCELLED if declined
CANCELLED     → final, cardholder cancelled
PROCESSED     → final, non-financial operation complete (tokenizeCard)
REFUNDED      → final, refund processed
CAPTURED      → final, pre-auth captured

operation — valid values for POST /transactions:

sale, refund, saleAndTokenizeCard, tokenizeCard
moToSale, moToRefund, moToPreAuthorization, moToReversal
preAuthorization, preAuthorizationIncrease, preAuthorizationCapture, preAuthorizationReversal
saleReversal, refundReversal
stopCurrentTransaction, pingDevice, printReceipt

Auth header: ApiKeyCloud: YOUR_API_KEY (not Authorization, not X-Api-Key)

Full parameter tables with types, required/optional flags, and enum values: Cloud API — Operations Reference

Full documentation​

• Get started
• Acquirer capabilities matrix
• Error codes
• Transaction recovery
• Release notes