--- schema_version: "1" id: c3c062d014db59b7d1063596561e1d8e57647568c6032706bc516ad4c70651a6 title: Adyen Terminal Discovery via Terminal Management API collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/commerce/264-0-0/rt_cms_hardware_ayden_term_manage_api.md canonical_url: https://help.salesforce.com/s/articleView?id=commerce.rt_cms_hardware_ayden_term_manage_api.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: e876ea274970bdb0ab091579ed9d862a45edd0dd75b9a5804c2c6f60ed7181e9 description: Turn on the terminal management APIs for your account and configure terminals with store associate-friendly names to take advantage of this feature. products: - Commerce release: "264" --- # Adyen Terminal Discovery via Terminal Management API Turn on the terminal management APIs for your account and configure terminals with store associate-friendly names to take advantage of this feature. Prerequisites: - Modern POS App build: 6.2.3 or later - Platform Support: iPhone & iPad - Offline Support: no The [Terminal Management API](https://docs.adyen.com/point-of-sale/managing-terminals/terminal-management-api) provides endpoints for retrieving information about your payment terminals and assigning them. ## Configuring Web service Account for Terminal Management Contact your Adyen support team to assist you in turning on terminal management APIs for your account. To configure the web service account for terminal management: 1. Log in to your Adyen portal and go to **Accounts > API Credentials**. ![The Ayden UI with API credentials highlighted in the Configure section.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_api_credentials.png) 2. Select the correct Web service user that has access to the company level or have the Admin create one for you. The **Accounts** tab under **Roles and Associated Accounts** section shall include the company's account. ![The Accounts tab under Roles and Associated Accounts section](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_associated_accts.png) 3. Make sure the **POS Terminal Management API** role is set up for the Web service user they currently use for PS Payment Gateway Integration. The **Roles** tab under **Roles and Associated Accounts** section shall include the company's account. ![The POS Terminal Management API page in the Ayden UI.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_term_mgmt_api.png) Make sure you have the API key for this Web service user. We have a way to configure this in Payment Gateway on CMS as Merchant key as Point of Sale uses it for refund API. If you're using the returns feature in the POS app, have this configured. ## Configuring Terminals with Store Associate-Friendly Names 1. Set the Display Label for every terminal by going to **Terminal > Customization > Signature and device name > Display label**. 2. A general recommendation is to keep the terminal names short and unique so it is easier for associate to quickly select the right terminal depending on the location inside the store. ![A friendly name configured in the Display label section of the Ayden Settings page.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_friendly_names.png) ## Configure Point of Sale CMS for Ayden Terminal Discovery Configure terminal discovery properties within the Adyen Payment Gateway so store workers can select payment terminals. ### Disabling QR Code Scanning We've added a QR scan code flag, so associates can scan a terminal QR code before placing an order through a terminal. This flag is obsolete with the discovery. We've kept that flag for backward compatibility so the existing POS apps continue to work as before.![The Scan QR Code for Terminal IP Address setting in Ayden is turned off.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_no_qr_code_scan.png) To test the new version of the app, we suggest copying the app settings and turning off this flag in the new copy. You can switch to this app configuration with a token and test the discovery. After the testing is complete with this app configuration, you can distribute the app to all devices and turn on the flag for all app configs. ### Configuring Payment Topology to 1:N 1. To set the topology at the store level, go to **Store Management > Store Settings > Store Register > Retrieve Current Payment Topology For Merchant**. 2. Set to "**1:N**." 3. Starting with version 8.4.1, printer topology can be configured at the register level in the CMS. To configure the payment terminal topology at register level, go to **Store Management > Register > Edit > Payment Topology and select "1:N"**. If topology is set to 1:N, the POS app doesn't show receipts on devices that support Adyen payment gateways (m400, P400, v400). This is even though the Adyen payment gateway is set to 1:N in the CMS. ### Configuring Terminal Management Settings in Adyen Payment Gateway 1. Go to **Integrations > Payment Gateways**. 2. Edit the **Adyen Payment Gateway** configuration. 3. Scroll to **Terminal Management Settings** to see the terminal discovery properties. ![The Terminal Management Settings in Ayden.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_terminal_mgmt.png) 4. Obtain the Adyen account details from your Adyen Portal: 1. **Adyen Company Account Name** - Name of the company account. ![The company's account name as shown in the Ayden portal.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_acct_name.png) 2. **Adyen Store Code** - Store code corresponding to this store on Adyen console. If filled, the store code filters the discovered terminals as well. ![The store code shown in the Ayden console.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_store_code.png) 3. **Adyen Terminal URL Prefix**: 4. Production: [https://postfmapi-live.adyen.com/postfmapi/terminal/v1](https://postfmapi-live.adyen.com/postfmapi/terminal/v1) 5. Test: [https://postfmapi-test.adyen.com/postfmapi/terminal/v1](https://postfmapi-test.adyen.com/postfmapi/terminal/v1) ![API URLs shown in the Ayden portal.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_url_prefix.png) ## POS App Flow for Ayden Terminal Discovery Associates can select a terminal for payment processing if logging into the Point of Sale Point of Sale (POS) app, which automatically discovers available terminals. ### Discovering Terminals on Cart If the associate logs in, the POS app automatically triggers the discovery of all available terminals in the store. If the associate is ready to check out, they select a terminal. The associate is presented with a list of terminals with their display names as set in the Adyen console. If no name was set, the app shows the terminal ID. If the associate doesn't see the terminal, they can select **Refresh List** to trigger the discovery of any newly connected terminals.![A list of Ayden payment terminals on the POS app screen.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_pos_refresh.png) Tapping on any reader from the list and clicking **Confirm** initiates a connection. Upon successful connection, the terminal prompts for payment. After a successful transaction, the terminal chosen is forgotten. The associate is asked to select the terminal again. ### Discovering Terminals in Device Manager The Device Manager screen also shows the list of all discovered terminals. If the associate chooses to connect the reader from the Device Manager screen, the app remembers the selection until it is manually disconnected or completes the current transaction. The associate has to make a selection again for the next transaction.![A list of available Ayden terminals in the POS app.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_pos_device_mgr.png) ### Switching Network Modes If the app loses network connectivity and switches to offline mode, the register defaults to a 1:1 topology for terminals. Users shall re-pair their preferred terminal through the Device Manager screen. While in offline mode, the list of terminals discovered via Terminal Management API remains available. After network connectivity is restored and the system switches back to online mode, the register resumes normal 1:N topology behavior.![The offline mode screen in the POS App after you've switched network modes.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_ayden_pos_offline_mode.png) ## Troubleshooting Ayden Terminal Discovery Errors When terminals don't appear in Device Manager, it's typically due to issues with Terminal Management API settings or permissions. If the Device Manager shows no terminals, there are several possible causes. ### Possible Cause 1: Terminal Management API settings are incorrect Verify that the merchant account, store code, and API prefix are set correctly. ### Possible Cause 2: Terminal Management API Permissions aren't given at the company account level Make sure the company level is checked for the WS user accounts. ![The company account in Ayden portal where you make sure company level is turned on for the WS user accounts.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_no_company_api_perms.png) ### Possible Cause 3: Terminal Management API Permissions are given at subaccount level Make sure all the subaccounts levels are unchecked for the WS user accounts. In the screenshot, the subaccount is checked and it shouldn’t be checked. ![The sub-account is turned on in Ayden when it shouldn't be.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_subacct_checked.png) ### Possible Cause 4: Web service API Key is mismatched The API key in CMS must match the exact WS API key in your Adyen console. In the screenshots, the last four letters of the key are the same. On Adyen:![The web service user configured in the Ayden portal.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_webservice_key_ayden.png) On CMS:![The web service user configured in Point of Sale CMS.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_cms_hardware_webservice_key_cms.png)