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 return404.
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.
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.
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 return401, while both missing and inaccessible transactions return404.

