Skip to content

Connection Troubleshooting

Hyvä POS is on the App Store

The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.

The most common connection issues, what causes them, and how to fix them.

"401 Unauthorized" Right After Setup with a Correct Token

You are using an integration token, and Magento is rejecting it as a standalone Bearer token. Since Magento 2.4.4 this is the default behavior. Enable:

Stores → Configuration → Services → OAuth → Consumer Settings → Allow OAuth Access Tokens to be used as standalone Bearer tokens → Yes

Then re-test the connection in the app.

"The Store URL Appears to Point at the Magento Admin Panel"

The Store URL field contains your admin URL, for example https://your-store.example/admin_x1y2. That does not work: in Magento, the admin front name owns every path under it, so the app's API requests get the admin login page back instead of API responses. The app detects this and reports it in the connection test.

Fix: enter the storefront base URL, the address customers use to shop, without the admin path. A separate admin domain (such as https://admin.your-store.example with no path) is fine; only the admin path breaks API routing.

Admin Login Fails While the Credentials Are Correct

Magento's Magento_TwoFactorAuth module, enabled by default, takes over the admin token endpoint the app uses and responds to a plain username-and-password request with "Please use the 2fa provider-specific endpoints to obtain a token." The app recognises that answer and asks for the code from the admin's authenticator app. With Google Authenticator as the store's provider, the sign-in completes with that code.

If no code prompt appears, or the code is refused:

  1. Check the store's provider under Stores → Configuration → Security → 2FA → Providers. The app supports Google Authenticator only. Duo Security, Authy and security keys need a browser, so for those accounts use an integration token (how). Integrations are not subject to admin 2FA.
  2. The admin has 2FA enabled but never finished setting it up. Magento then sends a setup email instead of accepting a code ("You are required to configure personal Two-Factor Authorization in order to login."). Complete the setup in the Magento admin first.
  3. Use OAuth 1.0a, which authenticates with signed requests instead of a login.

We do not recommend disabling 2FA for admin accounts to make admin login work.

"Session Expired" During the Day

Admin-login tokens expire after four hours by default. With stay signed in enabled the app renews the token in the background and retries the request; you will not normally see this. When renewal is not possible (the password changed, or stay signed in is off), the app shows a reconnect prompt: tap Not connected in the header and choose Reconnect, or sign in again.

If this happens often, switch the store to an integration token; those never expire.

The Store Is Unreachable

The header shows a Not connected pill whenever the app cannot reach the store. Tap it to see the reason and retry:

  • No network: the device has no internet connection. On the free tier no sale can be completed until the connection is back. On PRO, offline mode keeps selling and sends the sales later.
  • Store not responding: the server is down or not reachable from this network. Check whether the store loads in Safari on the same device.
  • Maintenance mode: Magento returns a maintenance page. The pill retries as soon as the store is back.

"Connect to the Store to Verify Your Sign-In"

A PRO register keeps a staff member's sign-in for 24 hours from the last time the store confirmed it. After that the store has to confirm the sign-in again, and the sign-in screen shows "Connect to the store to verify your sign-in. Your saved verification has expired." Sign in once the store is reachable. A staff member who never signed in on this device needs the store for their first sign-in.

"Your Staff Account Is No Longer Active on This Device"

The store no longer lists the signed-in staff member for this location: they were deactivated, removed, or unassigned from it. The register locks, and another staff member signs in.

"Refunds Need a Connection to the Store"

A PRO register on module 1.5.0 asks the store to authorize every refund before it pays out. The return is kept; pay it out once the store is reachable.

Everything Returns 404

If every request 404s, a reverse proxy or firewall in front of Magento is usually blocking the REST path. Verify that https://your-store.example/rest/V1/ is reachable from the device's network and not stripped by the proxy configuration.

Everything Returns 401

A staging or test store behind HTTP basic authentication returns a password prompt for every request the app cannot fill in: the wizard's connection test fails, and a connected register shows the store as unreachable. Either exempt Magento's REST API, everything under /rest/, from the basic authentication in the web server configuration, or allow the IP address the devices connect from. The storefront and the admin can stay behind the password.

Test from the device

Most connection problems are network problems. Opening the store URL in Safari on the same device shows whether the store is reachable, has a valid certificate, and is out of maintenance mode.