Terminal boarding

Create a terminal with POST /v2/terminals using the merchant's account ID, a processor configuration ID, and the identifiers assigned by the processor.

List available processor configurations with GET /v1/processor-configs using your API key for the target environment.
Use the request format for the configuration assigned to your merchant.
Send your API key in the X-Koard-apikey header.
Save the terminal_id returned by the API. Use it as {terminal_id} when reading or updating the terminal.

Common fields

Field	What to send
`account_id`	The merchant's Koard account ID
`processor_config_id`	A configuration ID returned by `GET /v1/processor-configs`
`name`	Terminal display name; `terminal_name` is also accepted. Some configurations require the merchant's business name.
`description`	Optional description; `terminal_description` is also accepted
`mid`	Assigned merchant identifier, where required by the selected configuration
`tid`	Assigned terminal identifier, where required by the selected configuration
`mcc`	Four-digit merchant category code
`var_sheet`	Processor-specific details described in the boarding guide for your configuration

Keep identifiers as strings and preserve leading zeros. Use the fields in the request example rather than copying a terminal response into a create request.

Choose a request format

Configuration	Boarding details
TSYS / TSYS with PIN / Netevia	Assigned TSYS VAR-sheet fields
Payroc	Top-level `mid` and `tid`; no VAR sheet
Elavon	Full `tid`, or bank and terminal numbers in `var_sheet`
Worldpay	Top-level `mid`, `tid`, `mcc`, and `var_sheet.bank_id`
Fiserv	Assigned MID/TID/MCC and the VAR-sheet format for your configuration
Silverflow	Create an acceptor with a BIN key, or use an existing acceptor belonging to the merchant
Cybersource	Assigned `tid` and the merchant's existing credentials in `var_sheet`

Each processor guide lists UAT and production configuration IDs at the top. Examples use UAT IDs where available; use the production ID for production requests. Merchant account IDs, credentials and other merchant details are fictional placeholders.

TSYS without PIN and TSYS with PIN require different configuration IDs. Contact support@koard.com for TSYS with PIN or Silverflow access, and for production access to processors other than Fiserv Nashville/Cybersource.

Addresses

Account and location addresses use street_line1, street_line2, city, state, zip, and country.

Most terminal VAR sheets use merchant_street_address, merchant_street_address2, merchant_city, merchant_state, merchant_postal_code, and country_code. TSYS uses acceptor_street_address for the street, merchant_location for the city, and city_code for the ZIP.

Use USA for a US address. US and 840 are also accepted as US country values. On create, an omitted or null country defaults to USA. On update, omit country to keep the current value, or send null to set it to USA. Elavon VAR sheets also accept 0840.

Use a two-letter state code and a five-digit ZIP or ZIP+4. Address requirements vary by processor. Boarding is currently available only in the US.

Update a terminal

Use PUT /v2/terminals/{terminal_id} and send only the fields you want to change. For example:

{
  "var_sheet": {
    "merchant_street_address2": "Suite 300"
  }
}

Omitted address fields keep their current values. Use the terminal's existing processor configuration when making an address-only change.

Available Processor Configurations

Silverflow