Frequently Asked Questions

Quick answers to the most common questions about Hygate.

General

What is Hygate?

Hygate is a smart access and payment platform that connects physical access points (smart locks and IoT devices) with online payment processing. You manage doors and devices from a dashboard, and guests pay for access by scanning QR codes.

What integrations does Hygate support?

Integration	What It Does
TTLock	Smart lock synchronization, QR access codes, passage mode
Shelly	IoT relay control, timed device sessions, power management
Stripe	Card payments, revenue collection, webhook handling
Resend	Email delivery for 2FA codes and notifications

What is the difference between a door and a device?

	Doors	Devices
Hardware	TTLock smart locks	Shelly IoT relays
Access model	QR code scanned at the lock	Timed session with countdown
Payment type	One-time access fee	Usage-based plan (e.g., €2.50 / 60 min)
Guest flow	Pay → Get QR code → Scan at lock	Pay → Select plan → Countdown starts → Timer ends
Session tracking	No — QR code is checked at the lock	Yes — full session lifecycle tracking
Passage mode	Yes — door stays unlocked on schedule	No — not applicable
Maintenance mode	Yes — payments blocked	Yes — payments blocked

Does Hygate support multiple currencies?

Currently, Hygate uses a single currency configured in Settings → General. The default and recommended currency is EUR. Contact your administrator if you need to change the currency.

Can I use Hygate without Stripe?

No. Stripe is the payment processor and is required for all payment collection. Hygate does not support cash, bank transfers, or alternative payment methods.

Can I use Hygate without TTLock or Shelly?

Yes. TTLock and Shelly are optional integrations:

Doors require TTLock — if you don't have smart locks, you won't use the Doors module
Devices require Shelly — if you don't have IoT relays, you won't use the Devices module

You can run Hygate with only one of these integrations active.

Getting Started

How do I add my first door?

Go to Settings → TTLock and configure your TTLock credentials
Go to Locations → Add Location — create a location
Go to Doors → Sync from TTLock
Select your locks, assign a location, set price and duration
Click Add Selected Doors
Generate a QR code and print it

See the Quick Start Guide for the full walkthrough.

How do I add my first device?

Go to Settings → Shelly and configure your Shelly Auth Key
Go to Locations → Add Location
Go to Devices → Sync from Shelly
Select your devices, assign a location
Click Add Selected Devices
Add at least one Usage Plan (price, duration, delay)
Test the payment flow with a Stripe test card

What's the difference between Administrator and Operator roles?

Capability	Administrator	Operator
Manage integrations	Yes	No
Manage team	Yes	No
View audit logs	Yes	No
Manage doors (add/edit/delete)	Yes	Edit only
Manage devices (add/edit/delete)	Yes	Edit only
Manage locations (add/delete)	Yes	No
Rename locations	Yes	Yes
Force-end sessions	Yes	No
Change 2FA settings	Yes	No

Payments

How do refunds work?

Refunds are processed through the Stripe Dashboard, not Hygate. When Stripe processes a refund:

It sends a charge.refunded webhook to Hygate
Hygate updates the payment status to REFUNDED

Hygate does not currently support initiating refunds from the admin panel.

Why did a payment fail?

Common reasons:

Card declined by the issuing bank
Insufficient funds
Card expired
3D Secure verification failed
Stripe API error

Check the Stripe Dashboard → Developers → Logs for details.

Can guests pay with multiple sessions at once?

No. Each device allows only one active session at a time. If a guest tries to pay while another session is active, they'll see an error message.

How long does a payment take to process?

Stripe payments typically complete in 2–5 seconds. After Stripe confirms the payment:

Door access: QR code generated immediately
Device access: Session activated with grace period, then relay turns on

Doors

What is passage mode?

Passage mode unlocks a door on a schedule so guests can enter without paying. When a guest scans the QR code during a passage window, they see "Free Access" instead of a payment form.

Passage mode is configured in the TTLock app or gateway settings, not in Hygate. Hygate displays the current passage mode status.

Can I change the door's price after it's been created?

Yes. Open the door, change the Access Price field, and save. The new price applies to all future payments. Existing completed payments are not affected.

The QR code isn't scanning. What do I do?

Re-generate and re-print the QR code at 300+ DPI
Ensure the print size is at least 2.5cm × 2.5cm
Print on matte paper (avoid glossy)
Laminate outdoor codes to protect from weather
Try with a different phone — some phones scan better than others

What happens when maintenance mode is enabled?

New payments are blocked — guests see a maintenance message
Existing active sessions continue unaffected
The door lock itself is not changed — Hygate only stops accepting payments
Operators can enable/disable maintenance mode

Devices

What is the delayed start / grace period?

The delay is the time between when a guest completes payment and when the session timer begins. This gives guests time to load laundry, connect a charging cable, or prepare equipment.

For example, a 60-minute wash with a 5-minute delay means:

Guest pays and the session starts
5-minute grace period: guest loads laundry
Timer starts: 60 minutes of actual usage begins
Total session: 65 minutes (5 + 60)

Can I have multiple usage plans for one device?

Yes. You can create multiple usage plans per device, each with different durations, delays, and prices. Guests select their preferred plan on the payment page.

What happens to the session if the Shelly device goes offline?

The reconciliation process (every 2 minutes) detects that the relay is off
The session is marked as CANCELLED with a failure reason
Audit logs record the interruption
The guest sees an error message on their session page

How do sessions end automatically?

A session cleanup cron job runs every 5 minutes:

Finds all ACTIVE sessions past their endsAt time
Sends a relay OFF command to Shelly
Marks the session as COMPLETED

Security

Should I enable 2FA?

Yes. We strongly recommend enabling 2FA for all user accounts, especially administrators. 2FA protects against credential theft — even if someone gets your password, they still can't log in without the second factor.

Authenticator App is the most secure option. Email OTP is convenient but slightly less secure.

How are integration credentials stored?

All integration credentials (Stripe, TTLock, Shelly, Resend) are encrypted at rest in the database using AES-256. They are only decrypted at the point of use.

Who can see audit logs?

Only Administrators can view audit logs. Operators do not have access to audit logs.

Can operators change integration settings?

No. Integration credentials (TTLock, Shelly, Stripe, Email) are accessible only to administrators.

Troubleshooting

The dashboard shows a module as red. What do I do?

Check the integration's settings:

TTLock red → Verify credentials in Settings → TTLock
Shelly red → Verify Auth Key in Settings → Shelly
Stripe red → Verify API keys in Settings → Stripe

Also check the service status pages:

A session is stuck and won't end. What do I do?

Go to Sessions
Find the active session
Click Force End

This immediately turns off the relay and marks the session as COMPLETED.

My QR code is showing the wrong price. What happened?

The price is locked when the guest initiates payment. If you changed the door price after the guest opened the payment page, the old price applies.

To correct:

Refund the payment via Stripe Dashboard
The guest re-purchases at the new price

Payment page isn't loading. What's wrong?

Verify the server is running and HTTPS is configured
Check the browser's developer console for errors
Try in an incognito/private browser window
Verify branding settings are correct (logo URL must be publicly accessible)

Data and Privacy

Where is my data stored?

Your data is stored in the PostgreSQL database configured in your DATABASE_URL environment variable. All sensitive data (credentials, tokens) is encrypted at rest.

How long do you keep payment records?

Payment records are retained indefinitely as part of your financial record-keeping. Contact your hosting provider for data retention policies and backup schedules.

Can I export my data?

Yes. The Reports module allows CSV export of payment and revenue data. Payment records can also be exported from the Payments module with filters applied.