API Reference

Koard API Reference

Koard API provides unified access to account onboarding, terminal management, payment processing, and reporting across all Koard environments.

Base URLs

Environment URL
UAT https://api.uat.koard.com
Production https://api.koard.com

UAT is an isolated sandbox environment — transactions processed there will not appear in card or merchant histories and no money moves.

API Versioning

All Koard API endpoints are versioned with a path prefix (/v1, /v2, /v3, etc.). The version is part of the URL path and is required for every request.

# Example: v1 endpoint
curl https://api.koard.com/v1/accounts/{account_id} \
  -H "x-koard-apikey: YOUR_API_KEY"

# Example: v2 endpoint
curl https://api.koard.com/v2/terminals \
  -H "x-koard-apikey: YOUR_API_KEY"

# Example: v3 endpoint
curl https://api.koard.com/v3/payments/{transaction_id}/capture \
  -H "x-koard-apikey: YOUR_API_KEY"

Current Versions by Resource

Resource Version(s) Path Prefix Notes
Accounts v1, v2 /v1/accounts, /v2/accounts v2 provisions MMS (Clerk org, SVIX app, API key) on creation
Terminals v2 /v2/terminals Paginated listing, search, and full CRUD
Locations v1 /v1/locations Create, update, and retrieve locations
Transactions v1, v2 /v2/transactions, /v1/transactions/{id} Use v2 GET for filtered, paginated searches; v1 retains transaction detail and passthrough-only edits
Payments v3 /v3/payment, /v3/preauth Card-present payment initiation via Tap to Pay
Payment Actions v1, v3 /v1/payments/{id}/…, /v3/payments/{id}/… Capture, auth increment, refund, reverse, adjust, confirm
Refunds v3 /v3/refund Standalone refund on completed transactions
Batches v1 /v1/batches Open, close, and edit settlement batches
API Keys v5 /v5/apikeys Scoped-permission keys; see Authentication

The /v5 surface currently exposes API-key management only (/v5/apikeys). Other resources such as payments, terminals, and accounts are served by their /v1–/v3 paths above — there is no /v5/payments, /v5/terminals, etc.

Version Lifecycle

  • Newer versions may change request/response schemas, add required fields, or alter default behavior. Always use the version shown in the endpoint path.
  • Older versions remain functional unless an endpoint is explicitly retired, and may not include the latest features. We recommend migrating to the latest available version for each resource.
  • Endpoint retirement is a breaking change. The transaction-search retirement below identifies the removed operation and its replacement.

Note: The version prefix (e.g. /v1/, /v2/, /v3/) is required in all request paths. Requests without a version prefix will return a 404.

Transaction search

Use GET /v2/transactions for filtered transaction searches. The former POST /v1/transactions/search operation is retired and returns 405 after the retirement release is deployed. Existing GET /v1/transactions and transaction detail routes remain available.

Send filters in the query string, with no JSON request body. Repeat account_id, status and transaction_type for multiple values. Omit unused filters; do not send empty strings or the literal string null for numeric or enum filters. Amounts are integer cents, and dates are integer milliseconds since epoch. 

curl --get 'https://api.uat.koard.com/v2/transactions' \
  -H 'X-Koard-apikey: YOUR_API_KEY' \
  --data-urlencode 'status=captured' \
  --data-urlencode 'status=refunded' \
  --data-urlencode 'min_amount=100' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

The response contains transactions, total, limit, offset and page. The default page size is 50, with a maximum of 200. The old POST default was 100, so set limit=100 explicitly if that page size is required. Replace the old JSON account_ids array with repeated account_id query parameters. An account filter can identify a merchant or a parent whose descendants should be included, subject to the caller's access. Without an account filter, v2 searches the caller's hierarchy, including for an admin caller; it does not request every account in the environment.

Passthrough-only transaction edits: PUT /v1/transactions/{transaction_id} is reserved for PSP passthrough EMV flows where Koard is only forwarding EMV data and later receiving the final transaction outcome from the PSP. It is not available for TSYS, Elavon, Fiserv, Worldpay, or other directly managed processor flows. Unsupported processor edits return 401, while both missing and inaccessible transactions return 404.

Next
Authentication