# Hotel guest wallet key service commissioning guide ## Overview {#overview} The commissioning of the wallet key solution for hotel guests is a collaborative effort between the hotel's wallet key service provider (i.e., Credential Manager), Salto business partner and the Salto team. This guide provides step-by-step instructions for setting up and commissioning the Salto-specific components of the Space hotel guest wallet key service solution. The solution enables hotel guests to use digital wallet keys - such as [Room Keys in Apple Wallet](https://support.apple.com/en-us/118273) - to access their rooms via Salto {{< glossary_term "access_point" >}}access points{{< /glossary_term >}}. By following this guide, you will be able to: - Verify hardware and firmware compatibility requirements - Configure the required Space licenses and software settings - Set up the [Hospitality API](https://developer.saltosystems.com/space/hospitality-api) connection between Salto Space and your system - Configure network and firewall rules for secure inbound connectivity - Connect Space to the Salto {{< glossary_term "wallethub" >}}WalletHub{{< /glossary_term >}} (dev or prod environment) - Configure locks and readers for wallet key provisioning This guide is intended for Salto business partners or Salto teams looking to commission and deploy the wallet key solution at a property. ## Commissioning setup {#commissioning-setup} To ensure a successful commissioning setup, the following aspects must be addressed: - Hardware compliance - Ensure hardware and firmware versions are compliant. - Space instance - All required license add-ons must be active within Space. - `SPACE-OPT-0041` **Wallet Guest Keys** - (Only for developers) `SPACE-OPT-0030` **Web Services defined by user** - see [integrator footnotes](#footnotes) for more details - The Space instance must be properly configured. - Space Server must be accessible by Hospitality API calling software instance (inbound). - Space setup - Proper configuration of both outbound and inbound endpoints. - Authentication credentials must be correctly set up and securely managed. ## Solution architecture {#solution-architecture} ![Solution architecture](images/space-hospitality-architecture.svg "Solution architecture") ## Hardware compliance {#hardware-compliance} Please contact your usual Salto representative to confirm the hardware and firmware versions required for product compliance and testing purposes. {{% info-panel %}} **Existing vs. new installations** - **Existing Space installation**: All hotel guest-facing readers must be surveyed to confirm hardware and firmware compliance before going live. Any non-compliant devices will need a firmware upgrade. - **New installation**: Wallet-enabled Salto devices must be purchased and installed at all hotel guest-facing access points, and updated to the latest available firmware version. In both cases, complete and share the **D3 Salto Asset Property Wallet HW Survey** document with Salto. {{% /info-panel %}} ## Step-by-step configuration: assets {#step-by-step-for-configuration-assets} Before starting the configuration in Space, you will need the following: - **TCI**: 3-byte unique identifier (a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) value made up of 6 characters) for the Wallet pass identification provided by the Wallet Key Service Provider. - **Wallet Key Service Provider's Hospitality API Endpoint information** (IP address and port) will be required to configure the property-protecting firewall and Windows server rules allowing incoming connections. - At the property level, the end customer (for example, the property's IT team) will need to configure both the property's firewall and the Windows server hosting Space to allow incoming connections. - **Space-hosting IP address and port number** will need to be shared with Wallet Key Service Provider. - **WalletHub credentials** must be obtained from Salto: to be securely provided to Wallet Key Service Providers by Salto. {{% info-panel %}} Please contact your usual Salto representative to start the process of obtaining WalletHub credentials. WalletHub credentials (username and password) are provided by Salto through a process that can take some time. Please make sure to submit the request with sufficient notice. {{% /info-panel %}} ## Step-by-step configuration: general {#step-by-step-configuration-general} 1. The hardware must be compatible and the firmware must be updated to ensure compliance. In addition, the hardware has to be correctly [SAM-configured during setup](/space/user-guide/operator/sam-and-issuing-options/wallet). 2. Install a dedicated [NCoder](/space/user-guide/operator/salto-network/encoders#ncoder): - Firmware number: 0172 - Firmware version: v01.15 or higher 3. Software and infrastructure (Space instance, network configuration, etc.) must be compliant with the requirements specified in the [Hospitality API documentation](https://developer.saltosystems.com/space/hospitality-api#prerequisites). ## Network configuration {#network-configuration} {{% warning-panel %}} **Network configuration requirements**: The solution requires allowing incoming connections to the Salto Space server. That means setting networking rules allowing incoming connections. It is highly recommended that such rules are kept as strict as possible. To do this, take into account the Space endpoint IP address and port, as well as the Wallet Key Service Provider IP address and port, in the inbound connectivity security rules (Firewall and Windows Defender Firewall rules). {{% /warning-panel %}} See network configuration requirements in the [Space Hospitality API documentation](https://developer.saltosystems.com/space/hospitality-api#network-requirements). ## NCoder dongle {#ncoder-dongle} An NCoder working in dongle mode is required for Wallet Key provisioning (check-in, etc.). {{% info-panel %}} In high-traffic environments where multiple guests are checking in simultaneously, consider installing multiple NCoder dongles to handle the increased credential issuing load. {{% /info-panel %}} See the section on [how to add encoders to the Salto Network in Salto Space](/space/user-guide/operator/salto-network/encoders) for more details. ## Step-by-step configuration: Space {#step-by-step-configuration-space} You need to configure Space as follows: ### Space license add-ons {#space-licenses} #### `SPACE-OPT-0041` {#space-opt-0041} Add-on activates the **Wallet Guest Keys** required feature. Make sure the feature is active prior to proceeding. #### `SPACE-OPT-0030` {#space-opt-0030} Only integrators need this license add-on for testing purposes, not the end customer. See [footnotes for more details](#footnotes). ### General options {#general-options} ![General options - wallet keys](images/general-options-wallet-keys.png "General options > Wallet keys") {.border} 1. Select **System** > **General options** > **Wallet keys** 2. Select the **Hospitality API** integration type from the drop-down menu. ### General options - API key generation {#general-options-api-key-generation} ![API key option](images/api-key.png "API key generation") {.border} 1. In the **API** panel, click **Generate**. The **Authentication (API key)** is automatically generated. This authentication key allows the connection between Space and Wallet Key Service Providers. 2. Share the API key with the Wallet Key Service Provider: the same generated authentication key must also be used in the Wallet Key Service Provider's environment (for example, Alliants). ### Space configurator {#space-configurator} ![Space configurator](images/space-configurator.png "Space configurator") {.border} Configure the **Hospitality API** port from the **Advanced** tab in the [ProAccess Space Configurator](/space/user-guide/systems-admin/check-configuration). The **ProAccess Space Configurator** icon is located on the desktop of the machine where Space is installed. Certificates to be used: - a) The customer can choose to send requests to a public IP or their own domain, using a CA-issued TLS certificate with a matching CN, which the integrator will verify. - b) Self-signed certificates are also permitted. - c) You can also use CA-verified certificates even if the requests are made to a public IP instead of a domain, but integrators cannot verify these certificates. {{% warning-panel %}} The same port must also be used in the Wallet Key Service Provider's environment. {{% /warning-panel %}} See also [Connectivity considerations for the Hospitality API](/space/user-guide/systems-admin/hospitality-api) ### Webhook {#webhook} ![Webhook configuration](images/webhook.png "Webhook configuration") {.border} (Optional) Select the **Enable** checkbox in the **WebHook** panel of the **Wallet keys** tab in **General options** to activate it. You can use the webhook to receive notifications about changes affecting issued wallet keys. However, keep in mind that these notifications follow a best-effort approach and are not guaranteed to be delivered in all scenarios. You will need to provide the following information to receive webhook notifications: - **Webhook URL**: URL where you want to receive the notifications. - **Webhook username**: username for basic authentication. - **Webhook password**: password for basic authentication. ### WalletHub {#wallethub} WalletHub is the Salto component responsible for managing wallet key credentials and provisioning them to the locks and readers. ![WalletHub configuration](images/wallethub.png "WalletHub configuration") {.border} 1. In the **WalletHub** panel, enter the username and password. **These details are provided by Salto.** 2. Click **Save**. 3. Click the **Test connection** button to verify the **WalletHub** data you have entered is correct. 4. Once verified, click **Activate**. Wallet keys are now configured and ready to be used. ### SAM & issuing {#sam-issuing} SAM & issuing configuration is required to enable the provisioning of wallet keys to the locks and readers. ![SAM & issuing configuration](images/sam.png "SAM & issuing configuration") {.border} - Select **System** > **SAM & issuing options** - In the **Active keys** list, check **Wallet** - In **Credential provider** select **Salto** - Enter the **TCI** value (a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) value made up of 6 characters). The **TCI** value is provided by the Wallet Key Service Provider. - Click **Generate key** to generate the key that will be used for wallet key provisioning. - Configure **Salto readers** with a [PPD](/space/user-guide/operator/system/ppd) (Portable programming device) See the full [SAM and issuing options for wallet keys](/space/user-guide/operator/sam-and-issuing-options/wallet) section for more details. ## Additional resources {#additional-resources} - [Space general options wallet keys](/space/user-guide/operator/general-options/wallet-keys) - [SAM and issuing options for wallet keys](/space/user-guide/operator/sam-and-issuing-options/wallet) - [Connectivity considerations for the Hospitality API](/space/user-guide/systems-admin/hospitality-api) - [Hospitality API documentation](https://developer.saltosystems.com/space/hospitality-api) ## Footnotes {#footnotes} ### SPACE-OPT-0030 license add-on {#space-opt-0030-license-add-on} {{% info-panel %}} The `SPACE-OPT-0030` license add-on activates the **Web Services defined by user**, which allows pointing to the WalletHub dev environment endpoint. This license is only required during integration/development. It is not required for production environments. ![Space license wallet key feature](images/space-license.png "Space license options") {.border} ### Pointing to WalletHub Dev environment {#pointing-to-wallethub-dev-environment} ![Space general options configuration - advanced parameters](images/advanced-params-wallethub-dev.png "Space general options configuration - advanced parameters") {.border} Dev: **ONLY** while working in the development phase - **WALLETHUB_URI**: - **WALLETHUB_ACCOUNT_URI**: Prod: for production environments - **WALLETHUB_URI**: - **WALLETHUB_ACCOUNT_URI**: {{% /info-panel %}}