Encode a Keycard Manually

Quick Encode

Most manual keycards take about 2 minutes once your encoder is online.

This guide helps you encode keycards manually and choose how new cards affect active cards.

Go to: Operations View → Encode Keycard

Availability

You only see Encode Keycard when Settings → Room Access is set to Keycard Encoding.

Encoding permission

Staff who can encode keycards can use the active-card check. They do not need permission to browse Access Codes.

Opera acknowledgement

If you use Opera through a PMS-integrated encoder, AVA treats a bare 201 as acceptance. AVA then waits five seconds for the encoder to settle before it returns control. It does not use reservation roomKeys metadata to prove one physical encode finished. Explicit terminal success or failure statuses still pass through unchanged. If Opera sends no terminal result, retry the same request once. AVA formats Valid From and Valid Until as hotel-local wall-clock values before sending them to Opera. That depends on a valid hotel timezone. If the hotel timezone is invalid or request timezone data conflicts, AVA stops before encoding.

Confirmation diagnostics

If confirmation fails, support can review the sanitized room snapshot, expected values, settle delay, poll count, and match results. AVA does not log guest data or key PIN values in this path.

Header-Level vs Reservation-Level Encoding

AVA provides two ways to encode keycards. Understanding the difference helps you issue duplicate or additional keycards without changing your settings.

Method	Where to Find It	Number of Keycards
Header-level (green button)	Top of the Operations View, next to Help	Always 1-10, regardless of settings
Reservation-level	Card icon button on a reservation card or row	Controlled by your Room Access setting

• The header-level button starts a manual flow without opening a reservation.
• The reservation-level button starts encoding for the selected reservation or room.
• Both flows can find an active manual keycard set before encoding.

Extra cards do not require re-encoding

Choose Encode DUPLICATE keycards when you need extra cards. Existing cards remain active.

Additional guest check-ins

If a room is already checked in, an additional guest can reopen the duplicate keycard flow later. Use Encode DUPLICATE keycards to encode the extra guest's card without replacing the active set.

Resolve the reservation room before encoding

After you select an encoder, AVA confirms the assigned room through the authenticated PMS lookup. If the reservation card has no usable room value, AVA uses that lookup automatically. AVA accepts any non-empty PMS room identity, including long AVA PMS identifiers. It then uses the resolved room identity and room number for keycard lookup and encoding.

This applies to reservation room access, check-in, and key management. Your NEW or DUPLICATE choice stays unchanged.

No room mapping change needed

You do not need to shorten or edit a valid PMS room identity. Room mapping remains necessary only when the encoder room name differs from the PMS room number.

Choose New or Duplicate Cards

When AVA finds an active manual keycard set, it shows two stacked choices.

Choice	Use it when	Result
Encode DUPLICATE keycards	You need an extra card	Current cards keep working.
Encode NEW keycards	You must replace the active set	Previous cards stop working.

Replacing cards deactivates earlier cards

Use Encode NEW keycards only when replacement is intended. Give guests the new cards immediately.

AVA checks the room, guest, and stay dates before showing these choices. It keeps the new request connected to the active set.

Start a New Manual Keycard Set

For a room without an active manual set, choose Encode NEW keycards for the first card. AVA creates the new set during that first successful encode. It then reuses that set for each Encode DUPLICATE keycards request.

New sets do not need a reservation number

You do not need to enter or create a reservation number for a new manual set. AVA assigns the set automatically after the first successful card.

Use Encode NEW keycards again only when you want earlier cards to stop working.

Quick Reference

Field	Required	Default or notes
Select Keycard Encoder	Yes	One online encoder is selected automatically. Select a specific online encoder when several are available.
Room Number	Yes	Select the PMS room number. The encoder room name appears as helper text. AVA sends this room number to Opera's external-room-key flow.
Guest Name	No	Optional.
Valid From	Yes	Defaults to current time.
Valid Until	Yes	Defaults to tomorrow at your configured keycard expiration time in your hotel's timezone. Falls back to 11:00 AM if the setting is missing or invalid.
Number of Keycards	No	Defaults to 2. Choose 1-10 whole cards.

AVA rejects non-integer card counts.

Room Number Display

The room list shows the PMS-facing room number first. If different, AVA shows the encoder room name in parentheses.

Encoder availability

Dynamic encoder lists use the live agent connection as the source of truth. If the encoder’s agent is connected and the tunnel is reachable, AVA shows it as Online. Static or direct encoder lists keep their existing behavior.

GreatLocks encoder choice

Each GreatLocks row represents one physical encoder and its connected Windows PC. When several are online, select the encoder for the PC you need. The selected encoder handles this keycard request.

Valid Until Default

AVA uses Settings → Room Access → Keycard Expiration Time for the default Valid Until time. If this setting is missing or invalid, AVA uses 11:00 AM. If a reservation has no checkout date, AVA still uses tomorrow at that configured time.

Start the Encoding Flow

1. Go to Operations View.

2. Select Encode Keycard.

   ✓ The Manual Keycard Encoding modal opens.

3. If one encoder is online, AVA selects it automatically.

4. If multiple encoders are online, select the target encoder with Online status. That status follows the live agent connection. For GreatLocks, choose the encoder linked to the Windows PC you need.

5. Select a Room Number from the dropdown list.

   ✓ You see the PMS room number as the main label. If mapped, you also see (Encoder: ...) as helper text.

6. Optional: enter Guest Name.

7. Set Valid From and Valid Until.

8. Choose the Number of Keycards.

9. Click Encode Keycard.

   ✓ AVA checks whether the room already has active manual keycards.

10. If AVA finds an active set, choose Encode DUPLICATE keycards or Encode NEW keycards.

✓ The keycard encoding flow opens with your selected operation. 11. Place each blank card on the encoder and follow the on-screen prompts.

✓ AVA shows the encoding result for each card.

Encode from a Reservation

1. Open Operations View → Check-ins or Operations View → Stay-overs.

2. Select Manage Pin / Encode Keycard for the reservation.

3. If active cards exist, choose Encode DUPLICATE keycards or Encode NEW keycards.

4. Select an online encoder when AVA asks.

   ✓ AVA confirms the assigned PMS room before opening the encoding modal. Long or internal-looking PMS room identifiers remain valid.

5. Place each blank card on the encoder and complete the prompts.

   ✓ Duplicate cards work alongside the existing set. ✓ New cards replace the existing set.

Troubleshooting

Duplicate option is not shown

What you see: You open a reservation, but AVA does not show the duplicate and new choices.

Why this happens: AVA shows these choices when it finds an active manual keycard set. New rooms can open the encoding flow directly.

Fix:

1. Confirm the reservation has the correct room and guest.
2. Click Refresh in the Operations View.
3. Try Manage Pin / Encode Keycard again.
4. Use the manual flow if you need to add a guest name for matching.

Reservation room cannot be determined

What you see: After selecting an encoder, AVA says "We could not determine the room for this reservation."

Fix:

1. Refresh the reservation or Operations View.
2. Confirm the reservation has an assigned room in your PMS.
3. Start the reservation-level encoding flow again.
4. Select an online encoder when AVA asks.
5. Contact support if the message returns after the PMS room is assigned.

AVA accepts valid PMS room identities, even when they look long or internal. Do not change the room identity manually.

Existing cards cannot be checked

What you see: AVA says it cannot check whether the room already has active cards.

Fix:

1. Click Try again.
2. If the lookup still fails, choose Start a new set only when replacement is intended.
3. Warn guests that earlier cards may stop working.

More than one active set matches

What you see: AVA says more than one active manual keycard set matches the room.

Fix:

1. Close the modal.
2. Reopen the manual flow and enter the guest's name.
3. If the match remains unclear, use Access Codes to choose the correct set.

Stay dates are missing

What you see: AVA says the stay dates are missing, so the active set cannot be reused.

Fix:

1. Refresh the reservation or wait for PMS synchronization.
2. Try the encoding flow again.
3. Choose Start a new set only when earlier cards should stop working.

Encode Keycard button missing

What you see: No Encode Keycard button in the Operations View.

Fix:

1. Go to Settings → Room Access.
2. Set Room Access Method to Keycard Encoding.
3. Return to the Operations View.

Encode Keycard button is disabled

What you see: The button is gray or shows "Missing merchant ID. Configure your account in Settings."

Fix:

1. Complete your account setup in Settings.
2. Refresh the page.

"No encoders found"

What you see: The encoder list shows "No encoders found."

Why this happens: AVA only lists dynamic encoders with live online status. That status comes from the connected agent and reachable tunnel.

Fix:

1. Go to Settings → Room Access.
2. Add or activate an encoder.
3. Return to Encode Keycard.

Encoder picker skipped

What you see: AVA opens the encoding screen without showing encoder choices.

Fix:

1. Confirm only one encoder is online.
2. Continue encoding. This behavior is expected.
3. Bring another encoder online if you need manual choice.

GreatLocks requires an encoder selection

What you see: AVA cannot continue a GreatLocks keycard request because several encoders are available.

Why this happens: Each GreatLocks agent serves one encoder. AVA needs your selection when more than one configured encoder can handle the request.

Fix:

1. Open the encoder list.
2. Select the GreatLocks encoder connected to the intended Windows PC.
3. Confirm its status shows Online.
4. Continue the keycard request.

If the correct encoder is missing, check its Encoder ID and agent status in Settings → Room Access. If two GreatLocks rows use the same ID, edit the rows and save unique IDs.

Encoder looks offline in the modal

What you see: The reservation keycard modal shows an encoder as offline, even though Settings → Room Access shows it connected.

Why this happens: The modal now uses the same agent connection state as the settings page. If the agent is connected and the tunnel is reachable, both views should match.

Fix:

1. Refresh Settings → Room Access and the reservation modal.
2. Check Registered Agents for the encoder card.
3. Fix the agent connection or tunnel if either view still shows offline.
4. Try encoding again.

Encode Keycard returns a failure

What you see: The modal closes with a failed request, or you see KEYCARD_ENCODE_FAILED.

Why this happens: The encoder returned false, so AVA treats the write as a real failure. It no longer shows a soft success response for that case.

Fix:

1. Check the encoder power, session, and connection status.
2. Retry the same encode request once.
3. If it fails again, switch to another online encoder.
4. Review the encoder logs or contact support with the exact error text.

Opera timezone mismatch

What you see: The modal fails before PMS returns a room key. You may see a timezone mismatch or invalid timezone error.

Why this happens: AVA uses the hotel's configured timezone for Opera keycards. It rejects invalid hotel timezone settings and conflicting request timezone data before encoding.

Fix:

1. Go to Settings → Essentials → Hotel Basic Details.
2. Confirm Timezone is set to the hotel's real timezone.
3. Save the setting if you changed it.
4. Refresh the reservation or reopen the manual flow.
5. Try Encode Keycard again.

Room number looks correct but encoding uses another room code

What you see: You pick room 101, but encoder logs show another room value.

Fix:

1. Go to Settings → Room Access → Keycard Encoder Room Mapping.
2. Find the selected PMS room.
3. Confirm the mapped Encoder Room Name is correct.
4. Save the mapping, then try encoding again.

Opera keycard request times out

What you see: The encoding flow stays open, then shows a failure or timeout.

Why this happens: AVA treats a bare Opera 201 as acceptance, then waits five seconds for the encoder to settle. It does not treat reservation roomKeys metadata as proof that one physical encode finished. Explicit terminal success or failure statuses still pass through unchanged. The request times out only when no terminal result appears before the settle window ends.

Fix:

1. Confirm the room number, key count, and validity window are still correct.
2. Check with your PMS admin that the external room key workflow is enabled.
3. If the room already encoded, do not create a duplicate by mistake.
4. Retry the same request once from the same reservation or manual flow.
5. Contact support with the room number, time, and error message if it still fails.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ You cannot open the manual encoding modal
• ❌ Encoding fails on every attempt
• ❌ No encoders appear after setup

Helpful to include:

• Encoder type and location
• Room number and dates used
• Screenshot of the error

Related Guides

• Set Up Keycard Encoders
• Keycard Encoder Troubleshooting
• Access Code Management