Boarding a Merchant with TSYS

You can board a TSYS merchant either through the Koard Merchant Management System (MMS) UI or programmatically via the API. Both paths require the same VAR sheet information provided by TSYS.

Via the MMS

After creating the merchant account, click New Terminal and select TSYS as the processor. You'll be presented with the TSYS VAR Sheet Information form.

Fill in all required fields (marked with *) using the values from the merchant's TSYS VAR sheet:

Once saved, assign the terminal to a location and generate merchant credentials as usual.

Via the API

Create Terminal — POST /v2/terminals

Request body

Example

curl https://api.uat.koard.com/v2/terminals \
  -X POST \
  -H "Authorization: Bearer $KOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "100200300001",
    "processor_config_id": "prc_live_tsys_us",
    "terminal_name": "Front Counter iPhone",
    "var_sheet": {
      "acquirer_bin": "123456",
      "merchant_number": "123456789012",
      "store_number": "0001",
      "terminal_number": "0001",
      "merchant_category_code": "5812",
      "merchant_name": "Bluebird Coffee Roasters",
      "merchant_location": "San Francisco",
      "merchant_state": "CA",
      "city_code": "94105",
      "acceptor_street_address": "123 Market Street",
      "industry_code": "R",
      "acceptor_phone": "4155551234",
      "acceptor_customer_service_phone": "4155551234"
    }
  }'

Update Terminal — PUT /v2/terminals/{terminal_id}

To correct or update VAR sheet fields after creation, send a PUT with a var_sheet object containing only the fields you want to change. All VAR sheet fields are optional on update.

Example

curl https://api.uat.koard.com/v2/terminals/500600700001 \
  -X PUT \
  -H "Authorization: Bearer $KOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "var_sheet": {
      "merchant_name": "Bluebird Coffee — Mission",
      "acceptor_street_address": "456 Valencia Street"
    }
  }'

VAR Sheet Fields

Required

Optional

Industry Codes

Use R for most mPOS use cases.

Language Indicators

Time Zone Codes

Gotchas

• merchant_number must be exactly 12 digits. TSYS will reject shorter values. Left-pad with zeros if your MID is fewer than 12 digits.
• store_number and terminal_number must be exactly 4 digits. Use 0001, not 1.
• city_code must be exactly 5 digits. Left-pad with a zero for ZIP codes starting with 0 (e.g. 02101 for Boston).
• Phone numbers must be exactly 10 digits. No dashes, spaces, or country codes — strip all formatting before submitting.
• merchant_name appears on cardholder statements. Make sure it matches the merchant's registered DBA name — discrepancies can trigger disputes.
• industry_code affects transaction routing. Using the wrong code can cause authorization failures or incorrect interchange rates.
• acquirer_bin is VAR sheet-level, not per-merchant. All merchants under the same TSYS VAR sheet share the same BIN. Do not confuse this with the merchant number.

Troubleshooting

400 Bad Request on create

• Check that all required VAR sheet fields are present.
• Verify merchant_number is 12 digits, store_number / terminal_number are 4 digits, city_code is 5 digits, and phone numbers are 10 digits.
• Confirm processor_config_id is a valid TSYS config ID for your environment.

Transactions erroring after boarding

• A VAR sheet field is likely incorrect. The most common culprits are acquirer_bin, merchant_number, store_number, and terminal_number — verify each matches exactly what TSYS has on file, including leading zeros.
• Check industry_code is appropriate for the merchant's transaction type — an incorrect code can cause authorization failures.
• If there is no open batch in our system for the terminal, transactions will error. Ensure a batch has been opened before processing payments.

Wrong merchant name on statements

• Use PUT /v2/terminals/{terminal_id} to update merchant_name in the var_sheet. Changes take effect on the next transaction.