Boarding a Merchant with Elavon

You can board an Elavon merchant either through the Koard Merchant Management System (MMS) UI or programmatically via the API. Elavon assigns the merchant a Bank Number and Terminal Number out-of-band. Those two values plus the standard top-level fields (mid, tid, mcc) are everything Koard needs from the merchant to board a terminal.

Before You Start

Elavon provisions merchants and terminals on their side; Koard never makes a "create merchant" call. Once provisioning is complete, the merchant's packet contains:

That's it. Everything else (Application ID, Vendor ID, Registration Key) is configured by Koard once per environment and never appears on a merchant VAR sheet.

How terminal_id is built

Elavon's wire format uses a single 22-digit Terminal_ID on every request. The spec is explicit (viaConex v4.090 §11.9 p.144):

Digits 1–6 = Bank Number (6 digits, fixed length, assigned by Elavon) Digits 7–22 = Terminal Number (16 digits, fixed length, assigned by Elavon)

The 22-digit Terminal_ID is pure concatenation — no padding, no spacing. You can supply either form:

Pick whichever your merchant's paperwork makes easier. Both end up with identical persisted state.

Via the MMS

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

Optional fields are accepted (see VAR Sheet Fields → Optional) but not required to onboard. Address, phone, DBA name and similar fields are only used when the merchant joins Elavon's Dynamic Merchant Data program, which is restricted-access and explicitly approved per merchant (viaConex §3 Block 03, p.22552–22557).

Via the API

Create Terminal — POST /v2/terminals

Request body

Example — pre-built 22-digit Terminal ID

curl https://api.uat.koard.com/v2/terminals \
  -X POST \
  -H "X-Koard-apikey: $KOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "100200300001",
    "processor_config_id": "prc_live_elavon_us",
    "terminal_name": "Front Counter iPhone",
    "mid": "123456789012",
    "tid": "0017340008025708085490",
    "mcc": "5812"
  }'

Example — split Bank + Terminal Number

curl https://api.uat.koard.com/v2/terminals \
  -X POST \
  -H "X-Koard-apikey: $KOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "100200300001",
    "processor_config_id": "prc_live_elavon_us",
    "terminal_name": "Front Counter iPhone",
    "mid": "123456789012",
    "mcc": "5812",
    "var_sheet": {
      "bank_number": "001734",
      "terminal_number": "0008025708085490"
    }
  }'

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.

VAR Sheet Fields

Required

Optional

Batch Management

Elavon merchants in production use clearing files (the .txt flat-file format defined by Elavon Clearing Format v4.69) for daily settlement. Koard handles this on the merchant's behalf — there is no merchant-driven batch open/close model in the live auth flow for Elavon.

If your merchant requires manual or automated batch scheduling via PUT /v2/terminals/{terminal_id} with a batch_schedule, see Automated Batch Scheduling.

Country & Currency — Cheat Sheet

The Koard API exposes the alpha forms (USD, USA) on the VAR sheet — the numeric EMV tags are constructed internally during the auth message build.

Gotchas

• mid and tid are top-level fields on the request, NOT inside var_sheet. This matches every other processor on Koard.
• tid is the 22-digit Elavon Terminal_ID — not a 3- or 4-digit lane number like TSYS or Worldpay. Build it from Bank Number + Terminal Number per the How terminal_id is built section, or paste the pre-concatenated form.
• Merchant DBA name / city / state / zip / phone are optional at auth and restricted to Elavon's Dynamic Merchant Data program. Don't add them unless your merchant is explicitly enrolled — Elavon silently ignores them otherwise (viaConex §3 Block 03).
• Country code is alpha-3 at the API level (USA, not 840). The numeric form only appears inside EMV TLV tags, which Koard builds internally.

Troubleshooting

400 Bad Request on create with bank_number / terminal_number errors

• Verify bank_number is exactly 6 digits and terminal_number is exactly 16 digits.
• Or supply the full 22-digit tid directly and omit the var_sheet split.

Transactions erroring with INVALID TERMINAL

• bank_number + terminal_number must match what Elavon has on file character-for-character, including leading zeros.

Wrong merchant name on statements

• Auth-path dynamic merchant fields are restricted. The DBA name on statements is set in the clearing file (BHR record), not on the auth. Update the merchant's DBA at Elavon directly or via the clearing pipeline.