Create Terminal

​

Onboard a payment processor terminal using processor-specific configuration data. This endpoint creates the terminal configuration and optionally updates the associated location.

Processor Support:

  • TSYS: Uses VAR sheet data with fields like acquirer_bin, merchant_number, store_number, terminal_number. See TSYSOnboardRequest.
  • Payroc: Uses processing_terminal_id and processing_merchant_id. See PayrocOnboardRequest.
  • Fiserv: Processor-specific configuration fields
  • Elavon: Processor-specific configuration fields
  • Worldpay: Processor-specific configuration fields

Surcharge Configuration:

  • Set surcharge_rate on the terminal to configure automatic surcharging (e.g., 3.5 for 3.5%)
  • Setting to null disables automatic surcharge logic
  • Setting to 0 means surcharges will NEVER be applied unless explicitly overridden
Body
required
application/json
    • account_id
      Type: string · Account ID
      required

      The merchant account ID

    • processor_config_id
      Type: string · Processor Config ID
      required

      TSYS processor configuration ID

    • var_sheet
      Type: object ·
      required
    • surcharge_basis
      Type: string | null · Surcharge Basisenum

      What the surcharge is calculated on. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level leaves it unset.

      values
      • total
      • subtotal
      • subtotal_plus_tax
      • subtotal_plus_tip
      • null
    • surcharge_confirmation_required
      Type: boolean | null · Surcharge Confirmation Required

      Whether the cardholder must confirm the surcharge before the sale proceeds. When true, sale/preauth returns a surcharge-pending state that must be confirmed before the transaction completes. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level defaults to no confirmation.

    • surcharge_rate
      Type: number | null · Surcharge Rate

      Surcharge percentage (e.g., 3.5 for 3.5%). Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits the value from the level above; a null at the account (root) level disables automatic surcharge logic (no surcharge is applied). 0 means surcharges are never applied unless explicitly overridden.

    • tax_basis
      Type: string | null · Tax Basisenum

      What the tax is calculated on. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level leaves it unset.

      values
      • total
      • subtotal
      • null
    • tax_rate
      Type: number | null · Tax Rate

      Tax percentage (e.g., 8.25 for 8.25%). Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level disables tax defaults.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v2/terminals
curl https://api.uat.koard.com/v2/terminals \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-koard-apikey: YOUR_SECRET_TOKEN' \
  --data '{
  "account_id": "",
  "processor_config_id": "",
  "surcharge_basis": "total",
  "surcharge_confirmation_required": null,
  "surcharge_rate": null,
  "tax_basis": "total",
  "tax_rate": null,
  "var_sheet": {
    "acceptor_customer_service_phone": "",
    "acceptor_phone": "",
    "acceptor_street_address": "",
    "acquirer_bin": "",
    "authentication_code": "",
    "city_code": "",
    "country_code": "840",
    "currency_code": "840",
    "gen_key": "",
    "industry_code": "",
    "language_indicator": "00",
    "merchant_category_code": "",
    "merchant_location": "",
    "merchant_name": "",
    "merchant_number": "",
    "merchant_state": "",
    "store_number": "",
    "terminal_number": "",
    "time_zone_diff": ""
  }
}'

{
  "account_id": "string",
  "agent_bank_number": null,
  "bin": null,
  "country_code": "840",
  "created_at": "2026-09-04T17:00:12.415Z",
  "currency_code": "USD",
  "deleted_at": null,
  "description": null,
  "merchant_category_code": null,
  "merchant_name": null,
  "mid": "string",
  "name": "string",
  "processor_config_id": "string",
  "serial_number": null,
  "status": "active",
  "surcharge_rate": null,
  "surcharge_basis": "total",
  "surcharge_confirmation_required": null,
  "tax_rate": null,
  "tax_basis": "total",
  "terminal_capability": "5",
  "terminal_id": "string",
  "tid": "string",
  "transactions": [],
  "updated_at": null,
  "var_sheet": null,
  "vid": null
}

Terminal created successfully