Skip to content

Terminals

Hyvä POS is in closed beta

Hyvä POS is currently in a closed beta (pilot phase) with a small group of merchants. It is not yet generally available: the App Store release follows the pilot, and features and configuration may still change - possibly in backwards-incompatible ways - before the general release. Want to take part? Sign up at hyva.io/pos.

A terminal is one register: one licensed device. You create terminals in the admin, attach a license, and activate a device with the terminal's activation code.

Creating a Terminal

  1. Open Hyvä POS → Store Setup → Terminals and add a new terminal.
  2. Give it a Name (for example Counter 1), assign it to a location, leave Active on, and save.
  3. The saved terminal has an Activation Code with a QR code on its edit form - that is what the device will scan.

The Device Identifier field fills in automatically when a device activates; you never type it. Saving the form cannot change or clear the device binding either - the binding only changes through the activation actions below, and each change writes an entry to the terminal's activity log.

The Activation Code

A 6-character one-time code (built from an alphabet without lookalike characters, so no I/O/0/1). Scan the QR code with the app or type the code; once a device has used it, the code is consumed.

Regenerate Activation Code on the terminal's edit form creates a fresh code, and is the standard move when replacing hardware or relinking a device. Regenerating:

  • clears the device binding, so the currently connected device is locked out at its next heartbeat (the admin warns you which device that is),
  • releases the license's device binding on hyva.io, so the license can be claimed by the new device,
  • does not disable the terminal - Active stays untouched; it is reserved as the deliberate admin lock-out switch.

Assigning a License

The License fieldset has one dropdown: Assigned License. It deliberately shows only licenses that can actually work:

  • licenses with status unused or active - expired, revoked and cancelled ones are hidden,
  • not already assigned to another terminal,
  • not bound (per the last hyva.io sync) to a different device - such a license would look assignable but the terminal would never receive a token; release it on the portal first (see buying and licensing).

One exception: the license currently assigned to this terminal always shows, marked (current), even when its status would normally hide it. So when a terminal is locked out over a revoked or cancelled license, the form shows you the cause instead of a misleading "-- No License --".

If the dropdown is empty, press Fetch Licenses on Hyvä POS → Store Setup → Licenses first - the dropdown only offers what Magento has synced.

Cloning Terminals

Setting up ten identical registers? Select existing terminals in the grid and use the Clone mass action. Each clone gets the source's name plus "(Copy)", the same location, its own fresh activation code, and no device or license. The clone's first activity-log entry reads "Cloned based on terminal X (ID: n)", so a grid full of copies stays traceable to its source. Rename the clones, attach licenses, and activate.

Device Status and the Heartbeat

The Device Status fieldset shows Last Seen At - the last heartbeat - plus created and updated timestamps. Activated devices check in every 5, 15, 30 or 60 minutes (a device setting, default 15). The heartbeat verifies the device is still the one bound to the terminal, refreshes the license token when a new one is available, and picks up configuration changes.

This is also your control channel: toggle Active off (or use the grid's mass deactivate) and the device locks at its next heartbeat; toggle it back on and the device recovers the same way. An inactive terminal also rejects activation codes until re-enabled.

The Activity Log

Every lifecycle event lands in the terminal's Activity Log fieldset, with a date, the event, details and the source (admin, pos_app or system):

Event Meaning
linked A device activated this terminal
transferred Activation moved the terminal from one device to another
unlinked The device binding was cleared (device relinked elsewhere, or unregistered from the app)
activated / deactivated An admin enabled / disabled the terminal
code_regenerated A new activation code was generated; any previous device was locked out
cloned The terminal was created as a clone, with the source terminal in the details
license_assigned / license_unassigned A license was attached / detached in the admin
license_status_changed A sync brought a new license status down from hyva.io
license_refresh_failed / license_refresh_recovered Token renewal failed / recovered

When something is off with a register, read this log first - it answers "what happened to this terminal and who did it".

Per-Terminal Overrides

The Override Location Config fieldset overrides selected location settings for this one terminal - for example Mollie Test Mode, so a single register can test Mollie payments while the rest of the location stays live. Each override has a Use Default checkbox; ticked inherits from the location.

Moving to a New Device

Two supported paths:

  • Replace: regenerate the terminal's activation code and activate it on the new device. The old device is signed out (it shows a terminal-reassigned screen) and the new device takes over the terminal, its settings and its license.
  • Fresh terminal: create a new terminal for the new device and keep the old one. Licenses move between terminals in the admin.

Each physical device has its own identity; a restored or cloned device intentionally does not inherit the original's terminal and must activate on its own. See activating your device.

Troubleshooting

  • The license dropdown does not show a license you bought: not synced yet (press Fetch Licenses), assigned to another terminal, or still bound to another device on hyva.io. Release it there or regenerate the old terminal's code.
  • A deactivated terminal keeps selling: it locks at its next heartbeat, not instantly. Check Last Seen At - a device that is offline or asleep locks the moment it next checks in.
  • The device says "Activation code not valid": the code was already used, or was regenerated since it was printed. Open the terminal, regenerate, and use the fresh code.
  • The device says the terminal is disabled: Active is off. Activation never overrides an admin lock-out; re-enable the terminal first.