Locations and Terminals
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.
A location is a physical store: address, receipt branding, payment methods, tax zone, MSI source. A terminal is one register at a location (location_id), paired with one device through activation. The REST terminal answers do not carry the device identifier or the activation code. Merchants manage both in the Magento admin; the routes below serve the device and external integrations.
| Method | Route | ACL | Purpose |
|---|---|---|---|
GET |
/V1/pos/locations |
Hyva_Pos::locations |
List locations (searchCriteria) |
GET |
/V1/pos/locations/:locationId · /code/:code |
Hyva_Pos::locations |
Fetch by id or code |
POST / PUT |
/V1/pos/locations · /:locationId |
Hyva_Pos::locations_manage |
Create / update |
DELETE |
/V1/pos/locations/:locationId |
Hyva_Pos::locations_manage |
Delete |
GET |
/V1/pos/terminals · /:terminalId |
Hyva_Pos::locations |
List (searchCriteria) and fetch terminals |
POST / PUT |
/V1/pos/terminals · /:terminalId |
Hyva_Pos::locations_manage |
Create / update |
DELETE |
/V1/pos/terminals/:terminalId |
Hyva_Pos::locations_manage |
Delete |
POST |
/V1/pos/terminals/activate |
Hyva_Pos::locations_manage |
Bind a device with a one-time activation code |
POST |
/V1/pos/terminals/deactivate |
Hyva_Pos::locations |
Release the device binding |
POST |
/V1/pos/terminals/:terminalId/heartbeat |
Hyva_Pos::locations |
Periodic device check-in |
POST |
/V1/pos/terminals/:terminalId/license/refresh |
Hyva_Pos::locations |
Force a license refresh from hyva.io |
Locations
The device lists locations during setup (GET /V1/pos/locations?searchCriteria[pageSize]=100) and receives its own location inside the terminal config payload. Create and update take the entity wrapped in a location key; the response is the saved row. Field names are the hyva_pos_location columns. The most commonly set ones:
{
"location": {
"name": "Amsterdam Flagship",
"code": "ams-01",
"street": "Main Street 1",
"city": "Amsterdam",
"postcode": "1234AB",
"country_id": "NL",
"phone": "+31 20 123 4567",
"vat_number": "NL123456789B01",
"website_id": 1,
"source_code": "ams_store",
"is_active": true,
"payment_methods": "cash,card",
"low_stock_threshold": 5,
"tax_use_address": true,
"receipt_header": "Thank you!",
"receipt_footer": "",
"card_payment_provider": "mollie",
"pickup_completed_status_code": "complete",
"layaway_deposit_min_percent": 25,
"layaway_expiry_days": 30,
"layaway_cancellation_fee_percent": 0
}
}
Nullable override fields (vat_number, receipt_logo_size, card_payment_provider, receipt_store_info_placement, and others) inherit the global default when null. Errors: 404 for unknown id or code, 400 (CouldNotSaveException / CouldNotDeleteException) on failed writes.
Terminals
Standard CRUD. Create and update take the entity wrapped in a terminal key:
A terminal is paired with a device only through activation. GET /V1/pos/terminals, GET /V1/pos/terminals/:terminalId and the save answers carry neither device_identifier nor activation_code, and a POST or PUT body that sets either is refused with 400 as an unsupported field. Filtering the list on device_identifier still works. A terminal row created in the admin carries a generated one-time activation code, shown in the admin grid, and a null activation_used_at.
Activation Flow
- An admin creates the terminal in Hyvä POS > Store Setup > Terminals; the grid shows the generated activation code.
- The cashier enters the code on the device during setup. The app calls:
POST /V1/pos/terminals/activate
{ "activationCode": "K7Q2M9", "deviceIdentifier": "8F3A61E2-5B2D-4C55-9A1E-0F47C2D9B3A1" }
- The server matches the code against terminals with an unused code, stamps
activation_used_at(codes are single-use), binds thedevice_identifier, and, when a license is linked and hyva.io credentials are configured, activates the license upstream. A license already bound to another device is auto-released and retried once. - The response carries everything the register needs to boot: the terminal, its location, the staff who may sign in, their roles, and
fiskaly_credentials, reserved for fiscal signing in Germany and Austria, where Hyvä POS is not yet available:
{
"terminal": { "terminal_id": 3, "name": "Front Desk", "location_id": 1, "is_active": true, "activation_used_at": "2026-08-12 09:14:02" },
"location": { "location_id": 1, "name": "Amsterdam Flagship", "code": "ams-01" },
"staff_list": [ { "staff_id": 7, "first_name": "Anna", "last_name": "de Vries", "email": "anna@example.com", "role_id": 2, "is_active": true } ],
"role_list": [ { "role_id": 2, "name": "Cashier", "permissions": "{\"place_orders\":true}", "is_active": true } ],
"fiskaly_credentials": null
}
- The device follows up with
GET /V1/pos/terminals/:terminalId/configfor the resolved config and license detail, and starts heartbeating.
Errors: 400 Invalid activation code format. (code must match ^[A-Za-z0-9]{4,12}$) or Invalid device identifier format. (^[a-zA-Z0-9-]{1,100}$); 404 Activation code not valid. for unknown or already-used codes (attempts are rate limited per device identifier); 400 This terminal is disabled. Enable it in the Magento admin before activating. when an admin has switched is_active off; 400 with parameters.outcome activation_refused when hyva.io refuses the license, with the reason_code hyva.io gave when it gave one; the message is hyva.io's sentence. When hyva.io gives no answer at all, reason_code is unreachable and the message reads Couldn't reach hyva.io to check the license. Check the store's connection and try again.
Deactivation (POST /V1/pos/terminals/deactivate)
Called by the device when the user unregisters the terminal in Settings. Body: { "terminalId": 3, "deviceIdentifier": "8F3A61E2-..." }. The server verifies the device identifier matches the registered one, then releases the binding. Returns true. Errors: 404 unknown terminal, 401 (AuthenticationException) on device mismatch.
Heartbeat (POST /V1/pos/terminals/:terminalId/heartbeat)
The device's periodic check-in. It updates last_seen_at, verifies the device, stores the register session the device reports, and returns terminal, config and license state in one call.
{
"deviceIdentifier": "8F3A61E2-...",
"openRegister": {
"open": true,
"heartbeat_interval": 900,
"session_id": "4C1D9E2A-6B7F-4E3A-9C55-1A2B3C4D5E6F",
"opened_at": "2026-10-20T07:12:04Z",
"business_date": "2026-10-20",
"timezone": "Europe/Amsterdam",
"opened_by": { "staff_id": 7, "name": "Veronica Costello" },
"document_count": 14,
"sales_total": "1290.50",
"currency": "EUR"
}
}
openRegister is optional. Send {"open": false, "heartbeat_interval": 900} when no session is open. sales_total is a decimal string in major units, and heartbeat_interval is in seconds. The module stores it per terminal in hyva_pos_terminal_session; every heartbeat that identifies its device and carries it overwrites the row, and a heartbeat without it leaves the stored state as it is. An open session is a live view and never becomes a closing; the closing is the register report the register uploads when it closes.
{
"is_active": true,
"device_identifier": "8F3A61E2-...",
"require_terminal_registration": true,
"config_hash": "…",
"staff_hash": "…",
"hyvaio_connection_ok": true,
"has_license": true,
"license_status": "active",
"license_expires_at": "2027-08-12 09:14:02",
"license_token": "eyJhbGciOi...",
"inactive_reason": null,
"last_upstream_check_at": "2026-08-12 06:00:11",
"last_upstream_check_succeeded": true
}
device_identifieris returned only to the paired device. A call withoutdeviceIdentifiergets the rest of the answer and an emptydevice_identifier.config_hashcovers the location row, every stored POS and tax setting, and the staff and roles the terminal config ships for the location: each active staff member assigned to the location or to all locations (ID,updated_at,passcode_updated_at,is_active,role_id,all_locations) and each role they hold (ID, name, permissions,is_active,updated_at). A new passcode, a role change, or a staff member added to or removed from the location moves it; a change to staff of another location does not. Pull the terminal config again when it moves.staff_hashis the staff and roles part ofconfig_hashon its own, andnullwhen the terminal has no location. Compare it between heartbeats: unchanged, the staff you hold still match the store.- An inactive terminal's answer carries neither hash.
inactive_reasonexplainsis_active: false:code_regenerated,license_revoked, ordeactivated(nullwhile active), so the lock screen shows the right message.last_upstream_check_at/last_upstream_check_succeededdescribe the most recent hyva.io refresh; the device does not contact hyva.io itself.
The terminal config returns the stored session to the paired device as open_register:
| Field | Content |
|---|---|
status |
open or closed as the last report stated; unknown when heartbeats arrive but none carried a session report within three heartbeat intervals (a register from before the field); not_reporting when no heartbeat arrived within three heartbeat intervals. A register that gives no interval counts 900 seconds per interval |
reported_at |
When the stored report arrived, UTC |
session |
The open session's facts (session_id, opened_at, business_date, timezone, opened_by, document_count, sales_total, currency); null unless the stored session is open |
Errors: 404 unknown terminal, 401 on device-identifier mismatch.
License Refresh (POST /V1/pos/terminals/:terminalId/license/refresh)
Triggered by the "Check License" button on the device; forces an immediate refresh against hyva.io instead of waiting for the scheduled check. Body: { "deviceIdentifier": "8F3A61E2-..." }.
{
"success": true,
"license_token": "eyJhbGciOi...",
"license_status": "active",
"license_expires_at": "2027-08-12 09:14:02",
"fiskaly_credentials": null,
"error": null
}
On upstream failure, success is false and error carries the hyva.io message. Errors: 404 unknown terminal, 401 on device-identifier mismatch. A paired terminal refuses an empty deviceIdentifier with Device mismatch., as it refuses a wrong one.