Set Up QRLOCK Digital Keys

Quick Setup

Prepare your QR Master details, map your rooms, then test one guest key. Plan about 15 minutes.

This guide helps you connect QRLOCK and deliver digital room keys through AVA.

Quick reference

Task	What you need	Where you do it
Connect QRLOCK	QR Master SID, Auth Token, and community number	Settings → Room Access
Map rooms	Exact PMS room IDs and QRLOCK rooms	QRLOCK Room Mapping
Choose delivery	Hosted link or direct QR image	Guest key delivery
Test access	A test reservation and a reachable QRLOCK reader	Check-in or reservation details
Manage access	A current key, guest email, or staff action	Reservation or Access Codes
Replace a lost key	Room-wide confirmation and current reservation data	Reissue

Before you start

Confirm these requirements:

• Your QRLOCK account provides a QR Master SID.
• You have the matching Auth Token.
• You know your QRLOCK Community Number.
• QRLOCK rooms are created and available in the vendor system.
• PMS room IDs are stable, unique strings.
• AVA uses a public HTTPS guest-key origin in production.
• Your staff role has Generate and Revoke permissions.

Keep credentials private

AVA encrypts QRLOCK credentials and guest links. Do not paste tokens into screenshots, support messages, or shared notes.

Confirm the guest-key service URL

Your deployment administrator must use the existing Room Access Service URL for guest links. AVA uses the application URL only when the Room Access URL is not configured.

Setting	Use
Room Access Service URL (ROOM_ACCESS_BASE_URL)	Primary origin for /guest-key and /guest-key/client.js
Application URL (APP_BASE_URL)	Fallback origin when the Room Access URL is unset

The selected URL must be a public HTTPS origin in production. It must not include a path, query, fragment, or login credentials. Do not add a separate guest-origin setting.

Ask your deployment administrator to confirm both guest routes load before testing issuance.

Connect QRLOCK

1. Go to Settings → Room Access.

2. Select the QR digital-key connection option.

3. Choose QRLOCK as the provider.

4. Enter your QR Master SID, Auth Token, and Community Number.

5. Select Test Connection.

6. Save the connection after the test succeeds.

   ✓ AVA shows Connected, masks the saved token, and loads the QRLOCK room inventory.

Supported QR readers

AVA supports QRALOCK and QRLOCK reader rooms through this digital-key flow. Other QR model families remain unavailable.

Choose guest key delivery

Choose how guests receive the QR key after you connect QRLOCK.

1. Find Guest key delivery in the QRLOCK settings.

2. Choose QR Master page (link) to keep the hosted QRLOCK page.

3. Choose QR image (direct image) to show the QR directly in AVA and guest emails.

4. Select Connect to QR Master to save the change.

   ✓ Existing QRLOCK credentials, room mappings, and access history stay unchanged.

Direct image mode retrieves the existing QR Master card as a PNG. It never issues a replacement card. AVA uses the QR Master checkout cutoff and caps image validity below 30 days.

The hosted link remains the default for existing and new configurations.

Map PMS rooms to QRLOCK rooms

1. Open QRLOCK Room Mapping in the QR digital-key settings.

2. Select a PMS room.

3. Select the matching QRLOCK room from the inventory.

4. Save the pending mappings.

5. Repeat for every room that should receive a QR key.

   ✓ AVA shows the room as mapped and ready for issuance.

QRLOCK can share a PMS room

You can keep a PIN-vendor mapping for the same PMS room. QRLOCK saves and changes only QRLOCK mappings. Other vendor mappings remain available for their own access flow.

Map every room explicitly

AVA does not guess a QRLOCK room from a similar name. An unmapped or ambiguous room cannot receive a QR key.

Deliver a guest QR key

For eligible QRLOCK room assignments, AVA issues one key after room assignment. AVA saves the key before it starts email delivery.

1. Complete the guest check-in.

2. Open Room Information for the checked-in room.

3. Check the QR key delivery status.

4. Use the guest-link action to copy the link when needed.

   ✓ The guest receives the room-information email with QR instructions.

After automatic or staff issuance, confirm the same key appears in access history. Then test the delivery selected in Guest key delivery.

For QR Master page (link), open the guest link and confirm the hosted page loads. For QR image (direct image), open the room information and confirm the QR image appears.

In direct-image mode, the room card keeps Open QR as a link available while the image loads. It remains available if image retrieval fails, so guests can use the authorized guest link without waiting for another key.

The email can include the current QR as an inline PNG with its expiry and keeps the guest link as a backup. AVA checks the current key immediately before sending, so it stops instead of sending stale QR material after withdrawal, expiry, or replacement.

Email retries reuse the same key. They do not create another vendor card.

If a staff-issued attempt failed after QRLOCK created the key, retrying can recover that saved key when the current reservation still matches it. AVA clears the stale error without creating another card or sending email automatically.

The room card can show Pending, Sent, or Staff assistance required. Email acceptance does not prove that the guest opened the door.

The link or image follows the reservation validity window. AVA keeps QRLOCK delivery separate from PIN access codes.

Hand off the QR key on the completion screen

After check-in, AVA shows a locally generated, scan-only QR code. It contains the complete AVA guest-key link for the issued room key.

1. Ask the guest to open the camera on their phone.

2. Ask them to scan the QR code on the completion screen.

3. Ask them to open the detected link.

   ✓ The guest's phone opens the issued AVA room-key page.

AVA shows scanning instructions in all seven supported languages. This handoff is the same for QR Master page (link) and QR image (direct image) delivery. The QR includes the guest-key token, so the guest does not need to enter a code. The kiosk does not open the link in a new tab or copy it to the clipboard.

If the QR does not render in CCI or ACI, select Retry QR. Retry redraws the same key URL without an API call, new issuance, or clipboard write. In a personal Pre-arrival session without kiosk identity, Copy guest link may appear. All other contexts keep copying disabled.

If AVA shows, "Please try again. If it still fails, contact the front desk," retry once. If the key is expired or unavailable, AVA asks the guest to contact the front desk.

Preview the current QR image

Use the staff preview to check the current QR without issuing another card.

1. Open Manage digital key for the QRLOCK reservation.

2. Review the current QR image and its displayed expiry.

3. Select Open QR image in new tab to open that same PNG.

   ✓ AVA retrieves the saved card image and keeps the existing guest link.

Previewing, opening, or refreshing the image does not issue or replace a card. If the room, key, or status changes, close the modal and reopen it. AVA then requests the image for the current key.

Send room information again

Use Email room information when the guest needs the current details again.

1. Open the checked-in reservation or room card.

2. Select Email room information.

3. Confirm the personal guest email.

   ✓ AVA resends the existing QR key and room details.

The email action does not issue a new key. Use a personal email address, not an OTA proxy address.

If delivery is temporarily unavailable, AVA retries the same delivery intent.

Issue or reissue access as staff

Use staff controls when automatic issuance did not occur, or when a replacement is required.

1. Open the reservation in Reservations or Access Codes.
2. Open Manage digital key.
3. Select Issue only when no current key exists.
4. Select Send when the key is ready.
5. Select Copy guest link to share the current guest link directly.

Staff issue and email delivery are separate actions. AVA checks the current room, dates, phone number, and room mapping before issuing.

If a QR key already exists, AVA can recover that key when the current phone is missing or no longer usable. It validates the saved holder, room mapping, stay, expiry, and withdrawal state before returning the existing key.

AVA also checks the current room, stay, and reservation references after PMS sync. If those details changed, refresh the reservation before trying again.

This recovery does not create a second QRLOCK card. It also does not update the guest or PMS phone number.

For multi-room reservations, AVA checks the selected room. A terminal selected room cannot be issued, reissued, or sent. The reservation history and withdrawal controls remain available.

Withdraw or reissue a QR key

Withdraw access when a guest checks out early or loses access permission. For a lost QR key, use the confirmed Reissue flow below. Standalone Withdraw is available only for QR Master page (link) delivery.

1. Open the reservation's room-access details.

2. For an early departure, select Withdraw for the current QR key.

3. Confirm the withdrawal.

4. If cancellation is still processing, select Retry cancellation after it becomes available.

5. Wait for vendor cancellation confirmation.

6. Refresh the status and select Reissue.

7. Read the room-wide warning and confirm the current room and key revision.

8. Confirm the new generation.

   ✓ AVA creates a fresh vendor card and guest link.

Replace a lost QR key for the whole room

Use Reissue directly when a guest loses a QR key or someone may still have its image. This replacement uses QR Master's room-wide loss report.

Do not select standalone Withdraw first for a lost key. In direct-image mode, Reissue replaces the standalone withdrawal action. In QR Master page mode, Withdraw remains available beside Reissue. Room-move cleanup follows the separate room-move flow.

Before replacement, AVA checks all of these details:

• You acknowledged that the replacement affects the configured vendor room.
• The key revision is still current.
• The selected room is in the PMS-assigned room list.
• The room mapping and reservation details still match.

Confirm the displayed key revision before you acknowledge the replacement.

If any check fails, AVA blocks cancellation and new issuance. The current key stays unchanged until you correct the reservation or refresh it.

Room-wide effect

Scanning the replacement invalidates earlier QR keys for that configured vendor room. This can include keys held by other guests in the same room. Confirm the room before continuing.

The replacement works with both QR Master page (link) and QR image (direct image) delivery. It does not automatically email the new key. Use Send, Copy guest link, or Email room information after replacement.

AVA records the cancelled issuance in access history. The old AVA link remains withdrawn, even if an old QR image still exists.

Three separate results

• AVA retrieval shows or downloads the saved QR image.
• Vendor cancellation withdraws the saved QR issuance.
• Physical invalidation happens when QR Master accepts the room-wide loss report.

An API success or cancelled AVA record does not prove that a physical lock rejected an old QR. Shared-door rules and later-key ordering remain hardware checks.

Do not retry an uncertain issue blindly

If AVA shows an unresolved or withdrawn key, wait for staff recovery. Automatic delivery never replaces that key without an explicit action.

The old AVA link stays withdrawn after reissue. Use only the newest guest link.

Checkout behavior

Checkout keeps the existing QR key behavior. Staff must withdraw access for an early departure. The stored validity window still controls normal expiry.

Move a guest to another room

AVA keeps the QR key generation linked to the room assignment.

1. Complete the PMS room move.
2. Refresh the reservation in AVA.
3. Wait for AVA to confirm the destination room.
4. Review the original key's cancellation status.
5. Issue access for the destination only after cancellation succeeds.

If the guest returns to the original room, use the revision-checked Reissue action. Do not repeat the PMS move after a cancellation failure.

What you see → Fix

The QRLOCK connection test fails

What you see: Test Connection fails or no QRLOCK inventory loads.

Fix:

1. Check the QR Master SID and Community Number.
2. Paste the Auth Token again without extra spaces.
3. Confirm your QRLOCK account can see the community and rooms.
4. Save the credentials, then run Test Connection again.

A room cannot receive a QR key

What you see: The QR digital-key action is unavailable for a reservation.

Fix:

1. Confirm the reservation has a room assigned.
2. Open QRLOCK Room Mapping.
3. Map the exact PMS room to one QRLOCK room.
4. Refresh the reservation and try again.

The guest link is withdrawn or unavailable

What you see: The old link says access is unavailable, or a replacement is missing.

Fix:

1. Confirm the latest QR key status in the reservation.
2. Do not reuse an older link after withdrawal or reissue.
3. If cancellation is confirmed, select Reissue.
4. Share only the newly generated link.

Replacement is blocked after a room or reservation change

What you see: AVA asks for a fresh confirmation or blocks Reissue.

Fix:

1. Refresh the reservation after the PMS update finishes.

2. Confirm the selected room is still assigned to this reservation.

3. Check that the QRLOCK mapping still matches the physical room.

4. Open Manage digital key again.

5. Confirm the room-wide warning and current key revision.

   ✓ AVA keeps the current key when the room context is stale or incomplete.

Do not retry repeatedly while cancellation is ambiguous. Contact support if the vendor rejected cancellation definitively.

The QR key email does not arrive

What you see: The room card shows a pending or failed email status.

Fix:

1. Confirm the guest has a personal email address.

2. Confirm the address is not an OTA proxy address.

3. Wait for the delivery retry to finish.

4. Select Email room information after the status refreshes.

5. Use Copy guest link if the guest needs access immediately.

   ✓ The current QR key remains unchanged while email delivery retries.

The direct QR image is unavailable

What you see: The QR image is unavailable, expired, or does not open.

Fix:

1. Confirm the reservation still has an active QRLOCK key.

2. Refresh the reservation and open the room information again.

3. If the page shows Try again, select it once.

4. If the key was withdrawn or expired, follow the confirmed withdrawal and reissue steps.

   ✓ Temporary failures keep the retry action available.

Do not issue a replacement only because image retrieval failed. Direct image mode reuses the existing QRLOCK card when its reservation details still match.

The completion QR does not appear

What you see: The completion QR is blank, or AVA shows a retry message.

Fix:

1. Select Retry QR once.

2. Ask the guest to scan the QR after it redraws.

3. Contact the front desk if the QR still does not appear.

   ✓ The retry redraws the current issued key without creating another key.

Do not expect a copy action on CCI, ACI, or enrolled kiosk screens.

QR key issuance returns a service error

What you see: Automatic or staff issuance returns a 503, and no history row or email link appears.

Fix:

1. Ask your deployment administrator to confirm the Room Access Service URL is configured.

2. Confirm /guest-key and /guest-key/client.js load from that public URL.

3. Confirm the URL has no path, query, fragment, or credentials.

4. Retry issuance after the Room Access Service release is healthy.

5. Confirm a new access-history row, guest link, and email delivery.

   ✓ AVA validates the guest route before creating a vendor key.

A QRLOCK mapping conflicts with another vendor

What you see: An older smart-lock vendor already uses the same PMS room.

Fix:

1. Open QRLOCK Room Mapping in the QR digital-key settings.

2. Select the exact PMS room and QRLOCK room.

3. Save the QRLOCK mapping without deleting the PIN-vendor mapping.

4. Confirm both vendor mappings remain visible in their own setup areas.

   ✓ QRLOCK uses its mapping, while the PIN vendor keeps its mapping.

If saving still fails, refresh the page and retry once. Do not reset the PIN vendor's mappings to resolve a QRLOCK conflict.

A room move blocks a replacement key

What you see: AVA says staff recovery is required before issuing a key.

Fix:

1. Refresh the reservation after the PMS confirms the destination.

2. Open the previous room's QR key status.

3. Confirm vendor cancellation succeeded.

4. Check the destination room mapping.

5. Select Reissue only when AVA enables it.

   ✓ AVA creates one replacement for the confirmed destination state.

An existing QR key is not found after a phone or staff-issue failure

What you see: A guest's phone is missing or changed, or a staff-issued attempt failed. AVA does not show the QR key that was already issued.

Fix:

1. Refresh the reservation after the PMS update finishes.

2. Confirm the selected room and stay dates match the issued key.

3. Open Manage digital key again.

4. Retry the staff action once.

5. Use Copy guest link or Send when AVA shows the recovered key.

6. Select Email room information when the guest needs the room details.

7. Do not select Issue repeatedly while recovery is still processing.

   ✓ AVA reuses the saved QR key when its room, stay, and mapping still match.

The retry clears a stale issuance error but does not send email automatically. If the room, stay, reservation reference, mapping, expiry, or withdrawal state changed, AVA keeps the key hidden until you refresh and resolve the mismatch. Contact support before issuing a replacement when the old key may still be active.

A selected room cannot use a digital-key action

What you see: Issue, Reissue, or Send is unavailable for one room.

Fix:

1. Confirm the selected room is not terminal in the PMS.
2. Select an active room from the reservation when appropriate.
3. Review the existing status and history for the terminal room.
4. Withdraw access only when the guest should no longer enter.

The QR scans but the door does not open

What you see: The hosted page or direct image displays a QR code, but the reader rejects it.

Fix:

1. Confirm the guest is using the latest link.
2. Check the reservation validity window and current time.
3. Confirm the QRLOCK room mapping matches the physical room.
4. Test the reader with the QRLOCK app or vendor tools.
5. Use the hotel's backup access method while you investigate.

If you recently replaced a lost key, wait for the vendor and lock to accept the room-wide loss report. An old QR image can remain visible but should no longer grant access after physical invalidation.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Credentials fail after you verify them
• ❌ A mapped room cannot issue a QR key
• ❌ Cancellation or reissue remains unresolved

Helpful to include:

• Hotel name and room number
• QRLOCK model and community number
• Screenshot of the status without credentials
• Reservation ID and time the issue started

Related Guides

• Smart Locks Overview
• Set Up Smart Lock Assignments
• Smart Lock Troubleshooting