Set Up Keycard Encoders

Quick Setup

Select an encoder type, choose a connection method if needed, then add encoders. Plan about 15 minutes.

This guide helps you configure encoder-first keycard encoding for kiosk or front desk use. It now covers Be-Tech Windows Agent setups too. Be-Tech uses the Windows Agent by default unless you configure a direct Base URL. Kiosk routing now lives on Settings → Kiosk. PMS-integrated keycards now discover encoder terminals from your PMS vendor before you add them. Be-Tech Windows Agent setups can recover a stopped client or service after a Windows restart or manual stop.

Quick reference

Task	What it does	Where you click
Select method	Enables keycard encoding	Room Access → Keycard Encoding
Choose encoder type	Selects your lock system	Encoder Type
Choose connection method	Direct vs. Windows Agent (Saflok/Be-Tech/GreatLocks)	Advanced options → Enable direct communication
Configure encoder	Adds server or credential details	Type-specific fields
Add encoders	Registers physical devices with real encoder IDs	Physical Encoder Devices
Load PMS encoders	Pulls available terminals from your PMS	Physical Encoder Devices → Load Encoders
Enable PMS card reading	Allows Entitlements to read physical PMS keycards	Enable physical keycard reading
Choose kiosk routing	Controls kiosk-specific routing rules	Settings → Kiosk → Device Routing
Download Windows Agent	Downloads the bootstrap package for the agent	Windows Agent
Check agent version	Shows installed and latest version status	Windows Agent
Update agent	Opens the update instructions modal	Update
Manage agent cards	Main cards show install, update, or reinstall actions	Windows Agent
Advanced agent actions	View logs, rotate secrets, or delete agents	Advanced options
Set encoding defaults	Cards per stay + expiry time	Encoding Options

Where to find it

Settings → Room Access → Keycard Encoding

Step 1: Select keycard method

1. Go to Settings → Room Access.
2. Select Keycard Encoding as the room access method.
3. Click Save.

Step 2: Choose encoder type

1. Scroll to Keycard Encoder Settings.

2. Select Saflok, Be-Tech, LockSDK, GreatLocks, or PMS Integration.

   ✓ AVA keeps only your selected encoder type enabled.

Step 3: Choose connection method

1. In Select Encoder Type, open Advanced options.
2. For Saflok, GreatLocks, or LockSDK, turn on Enable direct communication to bypass the Windows Agent.
3. Leave it off to use the Windows Agent (default).
4. Be-Tech uses the Windows Agent unless you already configured a direct Base URL.
5. PMS Integration uses direct communication only, so this step is skipped.

Step 4: Configure encoder system

Encoder Credentials Title

If you use multiple encoders, the section title shows Encoder Credentials & Devices.

If you're using Saflok

• Direct communication
  • Enter PMSI Server URL, Username, and Password.
  • The PMSI server must be reachable from the internet.
  • Click Test Connection.
• Windows Agent
  • Enter Username and Password only.
  • PMSI URL and connection testing are handled by the agent.
  • AVA keeps rechecking Saflok PMSI readiness, so slow boots and restarts usually recover automatically.
• Add encoder devices in Physical Encoder Devices (Encoder ID required).
• Optional: set Location for each encoder.
• If multiple kiosks share encoders, add routing from Settings → Kiosk → Device Routing.

If you're using Be-Tech

• Direct communication
  • Enter the Base URL for the Be-Tech service.
  • The service must be reachable from the internet.
  • Enter Hotel Name, Chain No, Workstation, and Reader No.
  • Set Category and Card Type if your Be-Tech setup requires them.
  • If Base URL is saved, AVA keeps Be-Tech in direct mode.
  • Click Test Connection to confirm the encoder responds.
• Windows Agent
  • Install the agent on the Windows PC connected to the Be-Tech workstation.
  • Enter Hotel Name, Chain No, Workstation, and Reader No.
  • The agent handles the local Be-Tech adapter and proxies vendor traffic.
  • AVA checks the agent on /check every 5 minutes.
  • After a Windows restart or manual stop, the tray can start the Be-Tech client and service automatically.
  • The tray refreshes Be-Tech readiness after recovery, without requiring a manual agent restart.
  • If no Base URL is saved, AVA falls back to the Windows Agent flow.
• Add encoder devices in Physical Encoder Devices.
• Optional: add routing from Settings → Kiosk → Device Routing if you use multiple encoders.

Multiple Be-Tech installations

The agent discovers normal Be-Tech installations automatically. Ask your deployment admin to set BETECH_CLIENT_PATH only when multiple protected installs cause ambiguity. The override must point inside a protected Windows Program Files folder.

If you're using GreatLocks

• Direct communication
  • Enter Server Name (optional), XHLSI Server IP Address, and TCP Port.
  • The server must be reachable from the internet.
  • GreatLocks supports one encoder per server.
  • Click Test Connection.
• Windows Agent
  • Server details are handled by the agent; no IP/port is required.
  • Install one Universal Encoder Agent on the PC connected to each GreatLocks encoder.

One GreatLocks agent per encoder

Add one row in Physical Encoder Devices for each GreatLocks encoder. Enter exactly one Encoder ID in each row. Use a unique ID for every row, such as front-desk or lobby-pc. AVA keeps existing IDs when you edit saved rows. Older rows without IDs receive stable IDs when AVA loads them. Then install one Universal Encoder Agent on the matching Windows PC. Each agent serves only its associated encoder.

Note: AVA uses the GreatLocks server record you save in Room Access. If you updated an older setup, click Save before Test Connection. If inventory sync is enabled, AVA reads building, floor, and room data through the active agent tunnel. Keep the agent online so room lists stay current. If your GreatLocks setup supports lift access, turn on Enable lift access. Then choose the mode your vendor supports:

• Room floor mapping uses building and floor values from your room mappings.
• Access code groups uses Common access codes for shared doors or lift groups.

AVA sends only one lift option type per card. When you use access code groups, AVA saves single digits as two-digit codes. You can type 1,2,3 or 01,02,03. Keep codes within your vendor's supported range.

If you're using LockSDK

• Direct communication
  • Add each LockSDK encoder in Physical Encoder Devices.
  • Enter Encoder ID and Service URL for each encoder.
  • Click Test Connection after adding encoder entries.
• Windows Agent
  • Add each LockSDK encoder in Physical Encoder Devices.
  • Register one Windows Agent per LockSDK encoder.
  • The agent card shows the matching encoder and live status.
• Optional: add routing from Settings → Kiosk → Device Routing if you use multiple encoders.
• For combined rooms, LockSDK supports up to 4 rooms and requires RF50/Mifare lock type 5.

If you're using PMS Integration

• Ensure a PMS integration is active (Cloudbeds or Opera).
• Set the PMS vendor to match your property before you load encoders.
• Turn on Enable PMS Encoder Integration.
• In Physical Encoder Devices, either:
  • Click Load Encoders and Add Selected, or
  • Click Add Encoder and enter Encoder ID and PMS Encoder ID.
• Loaded devices now keep the provider encoder ID directly.
• Rediscovery saves the workstation, encoder, interface, and outbound-code details needed for PMS card reads.
• Opera reads work only when those details identify one exact Door Lock route.
• Use Active to disable encoders you don’t want used.
• Turn on Enable physical keycard reading only after your PMS read API is validated.
• Click Save after changing the reading setting.
• If the list is empty, check your PMS vendor setting first.
• If you still see no encoders, read PMS encoder discovery returns no results.

PMS card reading is separate from encoding

PMS encoding can continue while physical card reading stays off. Entitlements hides scan controls until the PMS and Room Access capabilities allow reading. Keep reading off until your PMS provider confirms the read API works for your property.

PMS card-reading support

PMS vendor	Physical card reading	What you should do
Opera Cloud (OHIP)	Supported when the adapter advertises the capability	Complete hardware acceptance before enabling reading
Other PMS vendors	Not available unless the vendor advertises support	Use manual room or confirmation lookup

AVA fails closed when your PMS does not advertise physical card reading. Your existing keycard encoding workflow remains available.

Enable PMS card reading

PMS card reading uses the PMS transport directly. It does not require a Universal Encoder Agent session. AVA enables scanning only when your merchant setting and PMS capability both allow it.

1. Select PMS Integration under Encoder Type.

2. Confirm Enable PMS Encoder Integration is on.

3. Confirm at least one discovered encoder is Active.

4. Turn on Enable physical keycard reading.

5. Click Save.

6. Open Entitlements and reload the page.

   ✓ Start scanning appears when the PMS reports physical card reading support. ✓ Manual room and confirmation lookup remains available when scanning is unavailable.

PMS kiosk mappings

For PMS Integration, AVA first resolves the kiosk's Device Model mapping against active PMS encoder devices. If that mapping is unavailable or does not match, AVA uses the legacy kiosk mapping. Keep the target encoder Active and use its current PMS encoder name in Device Routing.

Opera route matching is exact

Opera card reads need one matching workstation, encoder ID, interface, and Door Lock outbound code. If Opera returns duplicate or incomplete routes, AVA disables reading instead of guessing. Ask your Opera administrator to correct the encoder catalog, then click Load Encoders again.

Saflok interface values

Opera may show an encoder interface value such as SL01. AVA uses that value to select the matching Door Lock route. The read request uses the discovered numeric outbound code instead. You do not need to change the value manually.

Routing moved

AVA now manages kiosk routing on Settings → Kiosk → Device Routing. The Room Access page keeps the encoder settings and points you here for routing.

Step 5: Set kiosk routing (optional)

Use this section only for kiosk-specific routing behavior:

1. Go to Settings → Kiosk.

2. Open Device Routing.

3. Turn on Enable guest selection to let guests choose an encoder at the kiosk.

4. Leave it off to add routing rules for each kiosk.

5. AVA saves those kiosk rules against the Mini MDM Device ID.

6. Older device ID mappings update automatically when you save.

   ✓ When guest selection is on, AVA hides manual routing rules. ⚠️ You still need at least one encoder device added in Physical Encoder Devices. ✓ AVA can send encode requests using encoderId without kiosk mapping.

Encoder selection behavior in operations

• If exactly one encoder is online, AVA auto-selects it.
• If multiple encoders are online, staff must select one explicitly.
• For GreatLocks, use the matching row for dynamic status or configuration actions.
• AVA cannot infer the target when multiple GreatLocks servers or agents are available.

Live online status

Online means AVA verified the encoder and its agent tunnel. Unknown means AVA could not verify the encoder state. Unknown does not confirm that the encoder is offline. The Status: line shows online only after that connection is live. If an encoder drops offline, fix the agent or tunnel first.

Step 6: Set up the Windows Agent (Windows Agent only)

If you did not enable Direct communication, install the Windows Agent:

1. Go to Windows Agent.

2. Click Download Windows Agent on a new card, or Reinstall on an existing one.

3. Install the agent on the Windows PC connected to the encoder.

4. If the card shows Not connected or Never online, extract the downloaded zip, then run download-installer.bat.

5. When the download finishes, run the installer .exe it saves.

   ✓ The agent appears under Registered Agents with status details. ✓ AVA uses this live status when deciding whether an encoder is available. ✓ Each card shows Installed version and, when available, Latest version. ✓ If the agent is current, you see Latest version installed. ✓ If the agent is outdated, click Update before Reinstall.

Be-Tech, Saflok, GreatLocks, and LockSDK can all use the Windows Agent. For GreatLocks, repeat the agent setup for every configured encoder and connected PC. Check that each agent uses the matching Encoder ID. When the agent is outdated, Update appears before Reinstall on the main card. Open Advanced options for View Logs, Rotate Secret, or Delete. Rotate Secret now opens a confirmation dialog before AVA disconnects the current agent.

Service controls

Be-Tech recovery normally starts the stopped client or service automatically. Use Start, Stop, or Restart in the Windows Agent tray when you need manual service control. If Windows asks for permission, approve the UAC prompt to continue. If you cancel the prompt, repeat the action and approve it.

What you see when the version is outdated

What you see: The card shows Outdated, or it says the installed version was not reported by heartbeat.

Fix:

1. Click Update.
2. Read the update modal.
3. Open the Windows Agent app.
4. Click Check for Update.
5. Install the offered update.
6. Refresh Settings → Room Access and confirm the version status is current.

The same version status appears on LockSDK agent cards too.

Step 7: Set encoding defaults

1. Set Number of Cards to Encode (typically 1–2).
2. Set Keycard Expiration Time (default: 11:00 AM). This time pre-fills Valid Until during manual keycard encoding.

Day-use reservations

If the reservation is explicitly day use and day use is enabled, AVA uses the resolved checkout time instead. Overnight reservations still use Keycard Expiration Time.

Optional: expand Advanced options to enable Heartbeat Monitor.

Optional: Map PMS rooms to encoder names

If your encoder uses room names that differ from your PMS:

• Use Keycard Room Mapping.

Troubleshooting

If encoders are not responding or cards fail to encode, use the full checklist:

• Keycard Encoder Troubleshooting

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Encoder settings save but devices stay offline
• ❌ Cards cannot be encoded for any room
• ❌ Agent never shows online in Registered Agents

Helpful to include:

• Encoder type and model
• Screenshot of Keycard Encoder Settings
• Time the issue started

Related Guides

• Keycard Encoders Overview
• Keycard Room Mapping
• Keycard Guest Instructions
• Keycard Encoder Troubleshooting