Boarding a Merchant

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.

  1. List available processor configurations with GET /v1/processor-configs using your API key for the target environment.
  2. Use the request format for the configuration assigned to your merchant.
  3. Send your API key in the X-Koard-apikey header.
  4. 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}, replacing {terminal_id} with the Koard ID returned when you created the terminal. This is different from the processor's tid. There is no PUT /v2/terminals without an ID.

Use an API key with terminals:edit and access to the terminal's merchant account. A merchant can update its own terminals; PSPs and partners can update terminals belonging to merchants in their account hierarchy.

Send only the fields you want to change. All request fields are optional. Omitted fields retain their current values, so you do not need to resend the create request or the complete terminal response.

curl -X PUT 'https://api.uat.koard.com/v2/terminals/YOUR_TERMINAL_ID' \
  -H 'X-Koard-apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Front Counter POS","mcc":"5812"}'
Field Update behavior
name, description Change the terminal display name or description. A null description clears it.
mid, tid, store_number, bin, vid, agent_bank_number Change assigned processor identifiers. Keep them as strings and preserve leading zeros.
mcc Change the four-digit merchant category code. Some configurations require it and reject null.
terminal_capability, currency_code, country_code, status Change terminal settings. Omitted country is preserved; null country becomes USA.
processor_config_id Switch to an available configuration. This may perform boarding with the new configuration. Omission or null retains the current configuration.
surcharge_rate, surcharge_confirmation_required, surcharge_basis, tax_rate, tax_basis Change terminal defaults. Percentage values are percentages, such as 3.5 for 3.5%. Null allows the applicable location or account default to take effect.
var_sheet Merge supplied processor-specific fields with the current VAR sheet. Use the field names in the configuration's boarding guide.
batch_schedule For configurations with editable scheduling, send an object to set the schedule or null to remove it. Omission preserves it. Managed and unsupported schedules cannot be changed through this field.

For an address-only change, send just the changed VAR-sheet fields. For example, on configurations using merchant_street_address2:

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

Omitted address fields keep their current values. Omit processor_config_id when making an address-only change. A var_sheet object merges supplied keys; var_sheet: null requests a clear and is rejected when it would remove required processor details. Null is not interchangeable with omission.

Unknown fields are rejected. Do not include read-only response fields such as terminal_id, account_id, timestamps, or processor_details in the body.

A successful update returns HTTP 200 and the complete updated terminal configuration. Read it again with GET /v2/terminals/{terminal_id}. See the Terminals API reference for the request schema and response fields.

Previous
Available Processor Configurations
Next
Silverflow