Koard API Reference

Koard API provides unified access to account onboarding, terminal management, payment facilitation, 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.

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

curl https://api.koard.com/v2/transactions \
  -H "x-koard-apikey: YOUR_API_KEY"

Current Paths by Resource

This reference lists the latest version of each endpoint. The table shows where each resource lives. Each operation's page shows its full path.

Resource Paths Notes
Accounts /v2/accounts to list and create. /v2/accounts/{account_id} to read one. /v1/accounts/{account_id} to update and delete. /v1/accounts/credentials and /v1/accounts/{account_id}/credentials for merchant SDK credentials. Create and manage merchant and partner accounts
Terminals /v2/terminals and /v2/terminals/{terminal_id} Paginated listing, search, and full CRUD
Locations /v1/locations and /v1/locations/{location_id} Create, update, and retrieve locations
Transactions /v2/transactions to search. /v2/transactions/{transaction_id} to read one. /v1/transactions/event/{event_id} to read one event. Filtered, paginated search and single transaction reads
Payment Actions /v4/payments/{transaction_id}/capture, /v2/payments/{transaction_id}/refund, /v2/payments/{transaction_id}/reverse, /v3/payments/{transaction_id}/auth, /v1/payments/{transaction_id}/adjust, /v1/payments/{transaction_id}/confirm Capture, refund, reverse, incremental auth, tip adjust, and surcharge confirmation
Batches /v1/batches and /v1/batches/{batch_id} Open, close, and edit settlement batches
API Keys /v5/apikeys and /v5/apikeys/{key_id} Scoped-permission keys; see Authentication

Card-present payments start in the SDK, which supplies the encrypted reader data.

The site version selector, API path versions, and SDK release versions are independent. The default site version contains the current references. Older selectable API references are historical; shared guide pages describe the current integration. Use the API path and SDK version shown in each example.

Account creation has separate merchant and partner request variants. Merchants require tax_id, mcc, and a US business address; partners omit merchant tax and payment defaults. See Creating Merchant and Partner Accounts.

Version Lifecycle

  • A newer version of an endpoint can change request and response schemas, add required fields, or alter default behavior. Always use the version shown in the endpoint path.
  • Retiring an endpoint is a breaking change. The transaction search section below names the retired operation and its replacement.

Note: The version prefix (for example /v1/ or /v2/) is required in all request paths. Requests without a version prefix return 404.

Pagination

List endpoints page in one of two ways, and some do not page at all. Check this table before you build a loop.

Endpoint Paging Page size
GET /v2/transactions limit and offset. The response carries total, limit, offset, and page. Default 50, maximum 200
GET /v2/terminals The same envelope Default 50, maximum 200
GET /v1/batches The same envelope Default 50, maximum 500
GET /v2/accounts, GET /v1/locations, GET /v5/apikeys, GET /v1/processor-configs, GET /v1/accounts/{account_id}/credentials None. The response is the full array. Not applicable

For a paged endpoint, read total from the first response, then raise offset by limit until you have every item. Keep filters and sorting the same for every page. page is the 1-based page that the offset falls on.

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.

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. 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.