Biometric Setting

Biometric Setting registers access-control devices such as Matrix COSEC, ZKTeco, or Suprema for member check-in, gate commands, and access events. Staff attendance from hardware is a separate roster/provider-certification workflow when enabled.

What this page is for

Who should use it

Owner, operations manager, front desk lead, platform admin

Where to find it

/admin/biometric-settings

Before you start

Register location, device type Biometric / access control, provider, device name/code, external device ID, serial number, and active status.
Supported access-control provider choices in the staff app are Matrix COSEC, ZKTeco, and Suprema.
For Matrix COSEC, collect the COSEC device/controller identifier, device serial, site/controller/group reference, push/callback endpoint status, and user identifier format from Matrix COSEC device or COSEC API/admin tools.
For ZKTeco, collect the device serial/id, ZKBioTime or device API endpoint reference if used, site/location mapping, and user id/card/fingerprint identifier format.
For Suprema, collect the device id/serial, BioStar or access-control server reference, site/group mapping, and user id/card/biometric identifier format.
Access-control readiness means a configured active access-control provider, active device, external device ID, member/person identifier mapping, online device state, and audit logging exist before staff rely on check-in or gate actions.
Copy the device identifier, serial, site/controller ID, or group ID from the vendor portal/device manager exactly as the provider exposes it.
In SquareOS Commerce Device, choose Location or Brand-wide, Type Biometric / access control, Provider, Name, Code, External device ID, and Serial number. Linked Razorpay account should stay None for access devices.
For live access commands, enter Command endpoint URL as the common vendor/middleware endpoint, or enter Open gate endpoint URL and Sync person endpoint URL when the vendor exposes separate routes. Enter Bearer / API token and Custom headers JSON when the middleware requires authorization, site code, tenant id, or appliance-specific headers.
Command retry attempts controls how many times SquareOS retries a vendor command after retryable HTTP/network failures. Keep it at 1 unless the vendor middleware honors the commandRequestId/idempotencyKey in the payload. Retry delay (ms) controls the pause between attempts and should stay short for sync-person commands; avoid repeated open-gate retries unless the adapter is explicitly idempotent.
For inbound device events, enter Access event signature secret when the vendor middleware signs callbacks with HMAC-SHA256, or Access event verify token when the vendor/API gateway sends a shared token. Supported callback token headers are x-webhook-token, x-access-token, x-access-control-token, and x-jameson-token. Supported signature headers are x-access-signature, x-access-control-signature, x-zkteco-signature, x-cosec-signature, x-suprema-signature, and x-signature.
Keep Safe/fake device mode enabled during setup, demo, dry-run, and vendor testing. Disable it only after endpoint, token, headers, device id, and provider-side command permissions have been verified with the hardware vendor.
Store member access identifiers, key-fob/card IDs, biometric user IDs, or SquareOS Client ID values against the correct person/client record before relying on automatic gate open.
Access events must map to the correct person or access identifier. SquareOS accepts personId directly, or resolves common adapter values such as externalRef, accessIdentifier, userId, cardId, cardNo, cardNumber, employeeCode, pin, uid, and identifier to a same-brand person/client code when possible. Unresolved values remain visible as externalRef for investigation.
Accepted entry/check-in events create a Scheduling check-in only after SquareOS resolves the person and the existing backend check-in eligibility rules allow it. Denied, blocked, rejected, failed, invalid, or unauthorized events are stored as access events and marked as skipped, not as successful check-ins.
If the vendor says access was granted but SquareOS cannot create the check-in because entitlement, location, duplicate, or booking policy fails, the access event remains stored and its payload records jamesonCheckIn status FAILED with the backend error so staff can investigate the mismatch.
Biometric Setting setup is not production certification by itself; live Open gate, Sync person, signed/tokenized access-event ingestion, denied-event proof, and check-in bridge outcomes must follow the Access hardware command, event, and check-in bridge lifecycle runbook before staff rely on hardware operations.
Biometric/access devices should be tested for staff-triggered gate open, automatic check-in event ingestion, denied access, and offline device recovery before relying on them for attendance or gate decisions.
Current backend contract: if Safe/fake device mode is enabled, Open gate and Sync person create audited simulated completed command records. If fake mode is off, the device must be active and have a configured command endpoint; missing endpoint records a FAILED command instead of simulated success. With fake mode off, SquareOS posts a JSON command with commandRequestId/idempotencyKey, device id, external device id, serial number, person id, reason, provider, and staff actor to the configured endpoint, retries configured retryable failures, then stores attempt count, retry policy, provider status/body, and final COMPLETED or FAILED state. Inbound access events post to POST /commerce/devices/:deviceId/access/events from an active device and must satisfy configured token or HMAC-SHA256 signature verification unless Safe/fake device mode is enabled. Accepted entry/check-in events bridge into Scheduling check-in with source ACCESS_CONTROL; denied events do not create check-ins. Vendor-specific SDK payload semantics and live Matrix COSEC/ZKTeco/Suprema hardware certification must still be approved before production reliance.

Daily workflow

In SquareOS, open Admin, Biometric Setting, choose Access control, provider Matrix COSEC, ZKTeco, or Suprema, then enter location, device ID/serial, code, command endpoint URLs, command auth token/custom headers if used, command retry attempts/delay only when the adapter is idempotent, access event signature secret or verify token, Safe/fake device mode, and status.
Enroll or map the member access identifier, send a signed/tokenized allowed check-in/access event, and confirm the AccessEvent payload shows jamesonCheckIn CREATED and the member appears on the profile Check-in page with source ACCESS_CONTROL.
Send a denied/rejected access event for the same identifier and confirm it appears in access-event/audit investigation with jamesonCheckIn SKIPPED, without creating a successful Check-in row.
Use staff-triggered gate open only after verifying permission, location, device online status, and audit logging.
Use Check-in and Audit Trail to investigate mismatched or missing events.
Disable devices that are offline, moved, or no longer trusted.

Watch out

Do not manually override access repeatedly without fixing the device/person mapping problem.

Use the left menu to open related pages in Integrations.
Use Ask Docs for questions that are already covered in this public documentation.