Tenant Portal

First-time workspace setup

Read this concept after setup steps 10–11 (Tenant categories + Emails) and before your first tenant moves in during step 14 Bookings. Optional portal add-ons: Services Marketplace (setup Services tab). Concept pairing: Concepts — Setup sequence after go-live.

Finding your way in this guide

Start with How Tenants Access the Portal, then Payments tab and Digital contract signing. Self-service: Tenant Self-Service. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Tenant Portal section cross-reference · Concepts — Concept cross-reference.

Vivin provides tenants with a web-based Tenant Portal — separate from the management platform used by your team. It gives tenants full visibility into their contract, payments, and property information while enabling self-service features that reduce the workload on your operations team.

Pair with other concepts

Portal payments and receipt allocation follow Payment Allocation; tenant add-on purchases pair with Services Marketplace; WhatsApp chatbot escalation contrasts with portal self-service in Automation & AI. Full pairing matrix: Concepts — Concept cross-reference.

How Tenants Access the Portal

The Tenant Portal supports two complementary entry paths:

Email access-link request (default screen)
On first load, tenants enter their email address and click Send access link.
If a matching booking is found for that email, Vivin sends a secure portal link.

Tenant Portal — email access-link request (default entry screen)

Direct portal link with booking credentials
Onboarding/check-in emails can include a direct portal URL that already contains:
- Booking ID (id) — the reservation identifier
- Access Code (code, when configured) — the booking-specific portal credential
Operators can also copy or preview that same booking-scoped URL from the booking Contract Info tab (Method of payments → Tenant Portal); see Bookings > Contract Info — Tenant Portal link.

Both paths resolve to the same booking-scoped authentication model.

These access links are typically included in onboarding/check-in emails configured in Settings > Emails.

Invalid or expired links

Booking links can stop working when a code has rotated, the link was revoked, or the URL was copied incorrectly. In that case the portal shows a clear recovery screen instead of the booking home — tenants can request a fresh email link or follow your support path.

Tenant Portal — invalid or expired booking link with request-new-link action

flowchart LR
  subgraph paths[Tenant entry paths]
    A[Email + Send access link] -->|Matching booking| B[Secure link in inbox]
    C[Direct URL with id / code] --> D[Same booking-scoped session]
  end
  B --> E[Tenant Portal home]
  D --> E

The diagram is conceptual: the product may show different intermediate screens (for example an access-code field), but both paths authenticate the tenant to one booking at a time.

info

The Tenant Portal does not use email/password accounts. Access is booking-based: secure links carry booking credentials, and sessions can be restored for returning users.

Signed-in home

Pair with other Tenant Portal sections

Home cards pair with Bookings > Contract Info (portal link copy), Settings > Emails (onboarding links), and FAQ — Tenant Portal. Full pairing matrix: Tenant Portal section cross-reference.

After a valid access link or email flow, tenants land on the Home screen: branded header, primary navigation (Payments, Utilities, Requests, Contract, Documents, Services, Account), and cards for outstanding balance, next payment, open requests, contract status, and lease summary (property code, address, check-in/out).

Tenant Portal — signed-in home with navigation, payment summary, and lease timeline (example booking AA-11-5D)

Payments tab

Pair with other Tenant Portal sections

Ledger and pay-in pair with Payment Allocation, Finance module, Handling a Late Payment — Step 1, and Make payment (Paywall) below. Full pairing matrix: Tenant Portal section cross-reference.

The Payments tab (/payments) is the tenant’s ledger view — not the same screen as Make payment (/paywall), which is the checkout flow documented under Make payment (Paywall).

When the account payment module is active for the booking, the tab shows:

Payment schedule — the same timeline tenants see on Home, listing scheduled charges with amounts, due dates, and status badges. This mirrors the Payment Plan tab in the management platform.
Transaction history — inbound and outbound ledger rows with search, sortable Date and Amount columns, pagination (10 rows per page), and Export CSV for the filtered set. Search accepts signed amounts — for example -610 finds a €610 refund line (#2301).
Receipt links — when operators attach Invoice / receipt files to the booking, inbound rows can show a Receipt control that opens the matched document.
Processed deposit refund (#2295) — after operators click Mark refunded, the Deposit Refund row shows the net cash returned to the tenant (minus prefix), not the full contract deposit. When charges were deducted from the deposit before refund, an explanatory note shows the breakdown (grossReversed, appliedToCharges, netToTenant). Transferred refunds (balance moved to another booking) show transferred status with €0 net to this tenant. Until a booking_deposit_refund row exists, the portal still shows the forecast/pending state — see Managing a Check-out — Step 5 and Glossary — Deposit refund summary (tenant-facing).

The page header includes Make payment when online pay-in is enabled and the booking has an outstanding or upcoming balance.

Tenant Portal — Payments tab with payment schedule timeline and transaction history table

info

If the payment module is not provisioned for the account, the Payments nav item is hidden and tenants are redirected to Home when they open /payments.

What Tenants Can See

Once logged in, tenants have access to:

Payment Schedule

The tenant can view their complete payment schedule — all scheduled charges with amounts, due dates, and payment status. On Home this appears as the payment timeline card; the full list lives on the Payments tab. This mirrors the Payment Plan tab in the management platform.

Payment History

When the payment module is active for the booking, tenants can review scheduled charges and payment-related activity on the Payments tab (transaction history with search, sort, CSV export, and receipt links). There is no separate “show payment history” preference in Settings > Preferences; visibility follows payment-module and portal configuration.

Contract Details

Full contract information including unit details, rental period, pricing, and terms.

Digital contract signing

Pair with other Tenant Portal sections

Signing gates pair with Settings > Preferences — Mandatory fields (settings-preferences-tenant-portal-contract-signing-required.png), Settings > Contract templates (PDF must exist before Sign contract), Tenant categories, FAQ — Tenant contract signing blocked (operator troubleshooting), Processing a New Booking — Step 4, and Settings > Emails (portal signing vs paper upload). Full pairing matrix: Tenant Portal section cross-reference.

When Vivin has generated a contract PDF for the booking, tenants can sign digitally from Home (Sign contract) or the Contract tab. Signing runs in a full-screen wizard with four steps:

Step	What the tenant does
Your Details	Confirms or fills profile fields (name, phone, nationality, ID metadata, fiscal data, IBAN, and related fields). Fields your account marks as Mandatory for contract signing show an asterisk and block Next until filled. Tenant categories can further lock fields the tenant may not edit.
Billing	Reviews or completes billing name, fiscal ID, and billing address when those fields are editable for the tenant’s category and booking state.
Review	Reads a summary of personal, ID, fiscal, and billing values with Edit shortcuts back to earlier steps. When Lease purpose is enabled and required on the account, the tenant picks an allowed value here before signing.
Sign	Scrolls through the contract PDF, acknowledges they have read it, draws a signature on the canvas, and submits. Escape closes the wizard without saving.

After a successful portal signature, Vivin stores signedContractPath on the booking — that satisfies After contract signed (and combined paid+signed) lifecycle check-in triggers. Uploading a signed PDF on management Contract Info does not run the same trigger evaluation; use Send Check-in email on Contract Info → Check-in & Check-out after a paper upload when requirements are met (bookings-detail-contract-check-in-out-emails.png). When tenants report missing arrival mail, see FAQ — automatic check-in email; when they cannot reach Sign, see FAQ — Tenant contract signing blocked.

If no contract PDF exists yet, Home and Contract guide the tenant to contact you or retry later instead of opening an empty sign flow — confirm Contract Info in management and your contract template workflow first (FAQ — Tenant contract signing blocked). Account Mandatory for contract signing toggles (illustrated on Preferences) map to asterisk gates on the Your Details step below.

Property Information

The portal displays the property name, address, and any relevant details about the unit the tenant is renting. When a floor is stored on the listing, the Home welcome line and lease summary append it after the street address — Vivin avoids duplicating the word “Floor” when the stored value already includes it (for example 2nd floor stays as written; 3 becomes Floor 3).

Entry codes

When enabled, tenants see an Entry codes card on Home with building, property, and unit access codes configured in the property's Access Lockers tab. Each level shows a masked value by default — tenants tap Reveal to read the code and Copy to paste it into a keypad or message.

The card appears only when all of the following are true:

Requirement	Detail
Account toggle	Allow to see entry codes is On under Settings → Preferences → Tenant Portal (defaults On).
Check-in email sent	Vivin has sent the booking's check-in email (`checkInEmailSentAt` is set) — same gate as other arrival content.
Active stay window	Current time is before the physical checkout instant (check-out date + time).
Not canceled	The reservation is not in a canceled state.
Configured codes	At least one of building, property, or unit access codes is non-empty on the listing/property.

When any requirement fails, the Entry codes card is hidden entirely (no empty placeholder).

Check-in email vs portal card

The check-in email always includes access codes from Access Lockers when that lifecycle email sends — independent of Allow to see entry codes. The Preferences toggle gates only the portal Home card (#2166). Operators who disable portal entry codes should still expect codes in check-in mail unless they change lifecycle email content separately.

Operator setup: configure codes on Listings → Access Lockers, confirm Managing a Check-in — Step 4 (check-in email + portal), and audit the toggle on Preferences → Tenant Portal. When tenants report missing codes on Home but received check-in mail, see FAQ — Entry codes in the portal.

Key Features

White-labelled — the portal carries your brand colours, logo, and identity, presenting a professional experience under your company name.
Automated tenant support (external channels) — AI-assisted responses are available through channels such as WhatsApp and email where configured (see Automation & AI). The Tenant Portal web UI does not include an in-portal chat screen today.
Secure access — tenants use booking-specific secure links/credentials, with no password management needed.

Portal access by tenant category

What each tenant can open in the portal (modules such as Contract, Payments, Utilities, and Services, plus which profile fields are editable) follows the tenant category assigned on their profile. Operators configure segments under Account Settings → Tenant categories; integration-created tenants can inherit a default for integrations category when none is set manually. To audit how many live bookings or receivables belong to a segment before you change portal modules account-wide, use the same category on Bookings — Other filters, Finance — Tenant category filter, or Tenants — Tenant category filter — see Portfolio KPI review — Step 6.

Utilities tab

When Allow to see utilities is enabled in Settings > Preferences — Tenant Portal and the booking is not in a refunded state, tenants open Utilities (/utilities) to review consumption and bill allocation for the property.

Area	What tenants see
Daily breakdown	Consumption heatmap / grid for the billing period — useful when operators enter monthly landlord bills in Entering Monthly Utility Bills.
Cost allocation	How shared utility costs are split across units and which overage charges may appear on the payment schedule.

If utilities are disabled for the booking or category, the tab shows a short message that utility billing is not enabled.

Tenant Portal — Utilities tab with daily consumption breakdown and cost allocation table

Operator setup: Utilities module (Connections, AI bill upload, Bills Included ceiling) and the per-booking utilities toggle in Preferences / tenant categories. External assistants surface the same overage context with booking-scoped Tenant MCP get-payment-info — see Entering Monthly Utility Bills — Step 4.

Online Payments

Pair with other Tenant Portal sections

Pay-in requires account payment module + Listings > Payments tab Property Payments Active — distinct from Preferences profile toggles. Card and vIBAN flows: Make payment (Paywall). Full pairing matrix: Tenant Portal section cross-reference.

Tenants can make payments directly through the portal. Multiple payment methods are supported:

Bank transfer — each booking can use a unique virtual IBAN as the transfer destination (shown to operators on the booking Contract tab and in contract templates via {{vIBAN}}). This is a dedicated receiving reference for rent — not the tenant's personal IBAN. It enables zero-commission bank transfers and automatic matching when the payment module is active.
Credit card — optional credit card payments where the commission is charged to the tenant only, at no cost to the operator.

Online payments require both of the following:

Tenant payment module active on the account — pay-in features (for example card or bank flows shown to tenants) are provisioned per account. If tenants never see payment options, confirm with Vivin support that the payment module is enabled for your organisation.
Property Payments Active — a per-property toggle in the Payments tab of each property.

Account Settings > Preferences controls account-wide tenant edit defaults (fiscal data, IBAN, tickets, services, utilities, and related defaults). Tenant categories can further restrict portal modules and fields per segment. Neither replaces the two requirements above for taking a payment online.

Make payment (Paywall)

When the booking has an outstanding or upcoming balance and online pay-in is enabled, tenants open Make payment from Home (balance card) or Payments (/paywall with the same booking id + code query parameters). The screen is a two-step flow:

Select an amount — radio options depend on what is owed: Pay overdue debt, Pay next payment, Pay overdue + next payment (when both apply), and Pay entire balance (full missingValue). When nothing is due, the amount section shows You have nothing to pay right now. Your payments are up to date. and payment-method controls stay disabled. Operators chasing the same balance see matching payment overdue rows on /notifications — row-click opens the booking sidebar for Handling a Late Payment — Step 1.
Select a payment method — Bank Transfer (IBAN) and/or Credit Card when the account has card pay-in provisioned (isPaymentCCFeatureActive).

Tenant Portal — Home balance card with overdue amount and Make payment

Tenant Portal — Make payment amount radios and payment-method tiles

Bank transfer (virtual IBAN)

Expanding Bank Transfer (IBAN) shows the booking’s virtual IBAN (same receiving reference operators see on Contract Info), a copy control, Easypay institution details, and a note that bank transfers can take up to 48 hours to match. Tenants must include the correct reference so Vivin can auto-allocate the in-payment.

Tenant Portal — Bank transfer panel with virtual IBAN and copy control

When your account is configured to encourage card pay-in for near-term due dates (noticeTenantToUseCC), the first expand of Bank Transfer may show a Payment Due Soon dialog recommending Credit Card for faster settlement. Escape, the X control, or the backdrop dismisses the modal; focus returns to the bank-transfer control.

Tenant Portal — Payment Due Soon modal when bank transfer is opened

Credit card (embedded checkout)

Credit Card creates a hosted checkout session for the selected amount, then embeds the provider page in an iframe on the same screen (no separate browser tab). The tile shows Faster & extra security, accepted card brands, and a +5% service fee note charged to the tenant. While the session is created, the UI shows Initializing payment…; on failure, a red panel shows the error with Try again.

Tenant Portal — Credit card checkout embedded in the Make payment screen

Successful card capture posts a webhook back to Vivin; the payment schedule and Home balance refresh on the next load. Operators reconcile the same in-payment on Finance → Transactions and the booking Transactions tab like any other card receipt.

Walkthrough: Home → Make payment → select amount → Bank Transfer (virtual IBAN) → Credit Card hosted checkout iframe.

Operator troubleshooting — blank credit-card iframe

If tenants report a blank or blocked credit-card area after Initializing payment…, the hosted checkout page may not be embeddable in their browser (for example strict X-Frame-Options or content blockers). Vivin serves checkout HTML with a scoped Content-Security-Policy: frame-ancestors allowlist so only Vivin tenant-portal origins can embed the form — card sessions should complete in-portal on *.vivin.app. Ask the tenant to retry on a desktop browser, disable frame-blocking extensions for the portal domain, and confirm the booking still has Property Payments Active and an active payment module. Persistent failures after a successful session create belong in support with the booking id and approximate time.

Maintenance & Support (Requests tab)

Pair with other Tenant Portal sections

Portal Requests pair with Operations module, Settings > Preferences (Allow to create tickets), and Bookings > Tickets tab. Full pairing matrix: Tenant Portal section cross-reference.

The sidebar label is Requests; the route is /help and the page heading is Maintenance & Support. Tenants use this area when Allow to create tickets is enabled in Settings > Preferences.

New Request

The New Request sub-tab collects:

Space — room or area selector when your property defines spaces
Issue title and description
Photo attachments — images for context (uploaded after the ticket row is created)

Tenant Portal — Requests tab with New Request form (space, title, description, attachments)

History

The History sub-tab lists submitted maintenance rows with status, dates, and Staff Notes when your team fills Tenant note on the Operations ticket. Deep links ?tab=history and ?focusRequestId=<ticketId> open History directly — Home uses these when a tenant taps View all N requests or follows a notification link.

Tenant Portal — Requests History tab with status cards and staff notes

Maintenance Requests

Tenants can submit maintenance requests from the portal:

Describe the issue with text and attach photos for full context
Track the status of their request from submission through to resolution
Read staff updates — when your team fills in Tenant note on the Operations ticket, the portal shows it on the request card as Staff Notes (teal highlight). Resolution description on the ticket is never shown in the portal; it is for internal closure notes only.
Requests automatically create tickets in the Operations module for your team to manage

This self-service capability reduces phone calls and emails to your team while ensuring maintenance issues are documented with photographic evidence from the start.

Errors, timeouts, and recovery

The Tenant Portal uses booking-scoped sessions — when data cannot load, tenants see actionable copy instead of a blank screen or developer error text:

Situation	What tenants see
Portal bootstrap cannot load the signed-in shell (fatal error before tabs render)	Something went wrong with the error detail, Try again (reload), and a contact support link to vivin.app/contact
Booking home cannot load (network timeout, 5xx, or no response)	Friendly retry message (for example trouble reaching the service or check your connection) — not raw API errors such as Network Error
Send access link with an unknown email	Server validation message when the API returns one; otherwise generic guidance to check the address
Request history API fails with no cached rows	Couldn’t load your requests panel with Try again — distinct from the genuine No requests yet empty state
Maintenance submit succeeds but photo upload fails (#1487)	Amber banner Request submitted without attachments — the Operations ticket was created, but files did not save. Detail copy asks the tenant to retry or contact support; the History tab opens so they can confirm the row exists without photos
Deep link `?focusRequestId=` does not match any request	Amber not found hint — the link may be stale or the request was removed
Modals, sidebars, lightbox, install prompt	Escape dismisses the overlay (same pattern as the management app’s slide-outs)
Credit card checkout fails to load or iframe stays blank	Red error with Try again after Initializing payment…, or an empty iframe — retry, check ad blockers / strict browser privacy settings, confirm payment module + Property Payments Active; see Make payment — Credit card
Make payment with zero balance	You have nothing to pay right now — methods disabled until a charge is due or overdue

On Home, the Open requests card lists up to three active maintenance rows. When more are open, a View all N requests link opens the full Help tab so tenants are not left thinking only three exist.

Operators troubleshooting tenant reports should confirm booking credentials, payment-module provisioning, and Preferences / tenant category gates before assuming a portal defect.

Documents tab

Pair with other Tenant Portal sections

Shared files pair with Bookings > Files tab (operator uploads) and Managing a Check-in (ID and contract handoffs). Full pairing matrix: Tenant Portal section cross-reference.

Documents (/files) lists booking files operators attach in the management app (contract PDFs, invoices, ID scans, and other categories). Tenants can preview supported types in a lightbox (images and embeddable PDFs) and download any file they are allowed to see.

When operators upload from the booking Files tab in Bookings, each shared file appears on the portal with its category label, upload date, and row actions (Preview / Download depending on type). The list refreshes on each visit so new uploads appear without re-sending the portal link.

When files are attached, tenants see a populated grid instead of the empty state:

Tenant Portal — Documents tab with attached booking files, category labels, and preview/download actions

When no files are shared yet, the tab shows an empty state instead of an error.

Tenant Portal — Documents tab empty state when no files are attached to the booking

info

On mobile, Documents is reachable from the More bottom-nav item rather than the primary tab bar.

Account tab

Pair with other Tenant Portal sections

Editable profile fields pair with Tenant categories (field locks), Tenants module (operator-side profile), and mandatory-for-signing gates in Preferences. Full pairing matrix: Tenant Portal section cross-reference.

Account (/account) is where tenants update profile and billing fields your Preferences and tenant categories allow:

Section	Typical fields
Personal information	Name, phone, nationality, ID document metadata, fiscal ID and address
Bank account	European vs non-European toggle, IBAN, SWIFT/BIC, and related bank address fields
Billing information	Company billing toggle, billing name, fiscal ID, billing address

Locked fields show read-only values or hide entirely per category portal access rules. The page refetches booking data on each visit so changes made by operators in management appear without a full browser reload.

Mandatory-for-signing fields configured under Preferences are enforced here and in the contract signing wizard — not only on Account.

Services catalogue

Pair with other Tenant Portal sections

Add-on purchases pair with Services Marketplace, Settings > Services, and Payment Allocation (Layer 1 schedule lines). Full pairing matrix: Tenant Portal section cross-reference.

When Allow to see services is enabled in Settings > Preferences — Tenant Portal, tenants can open the Services area of the portal, browse your Services catalogue, and submit requests for one-time or monthly add-ons.

Cards — Each offering shows name, optional image, price, billing type (One-time or Monthly), and an optional description.
Property scope — The catalogue lists only services that apply to the tenant’s property. Offerings configured with All properties in Settings > Services appear for everyone; services restricted to specific properties are hidden when the tenant’s booking is not on one of those properties.
Description preview — If you enter a long description in Settings, the portal shows a short preview on the card (about two lines, with an ellipsis when the rest is hidden). The same preview pattern appears in the confirmation panel before the tenant confirms a request. Put the most important details first, or use the optional Link field in Settings to point to full terms, a booking page, or an external provider.
Billing — For standard services, confirming a request creates a charge on the payment schedule immediately. For approval-gated offerings (configured with Requires approval in Settings > Services), the card shows Awaiting approval after submit — no charge until a manager approves in the Requests tab. Tenants can cancel a pending request from the portal; rejected requests may show the operator’s optional reason.
Approval-gated services — Identified in management by the Approval required badge on the catalogue card. The portal blocks duplicate pending requests for the same service on one booking until the current request is approved, rejected, or cancelled.

Tenant Portal — Services catalogue with one-time and monthly cards, description preview, and Request Service

Before confirming, tenants review the selected offering in a confirmation panel (price, billing type, and description preview):

Tenant Portal — service request confirmation panel before submit

Walkthrough: Home → Services → Request Service on a catalogue card → review the confirmation panel (example booking, catalogue with Booking Premium).

Branding

The portal is white-labelled with your company's identity:

Logo — displayed in the header (configured in Settings > General Information)
Brand Color — the primary accent color used throughout the interface (configured in Settings > General Information)
Company Name — displayed in the portal and in all communications

This allows each property management company to present a professional, fully branded experience to their tenants.

Tenant Self-Service

Depending on your configuration in Settings > Preferences > Tenant Portal, tenants may be able to:

Area (Preferences toggles)	What the tenant can do when enabled
Fiscal / ID / billing / IBAN fields	Update the corresponding profile and bank fields before or after contract signature, per toggle.
Allow to create tickets	Submit maintenance requests with attachments (creates Operations tickets).
Allow to see services	Browse the services catalogue and submit service requests.
Allow to see utilities	View utility consumption and charges.

Contract signing gates — Under the same Tenant Portal card, Mandatory for contract signing can require any combination of Your Details fields (name, phone, nationality, identification and fiscal data, IBAN, and related ID metadata) to be filled before the tenant can sign. Each enabled toggle is enforced in the portal UI and on the sign API. See Preferences — Mandatory fields before contract signing. Tenant categories can further narrow portal modules and editable fields per segment.

Paying online follows Online Payments: account payment module + Property Payments Active, not a separate “online payments” row on the Preferences page.

Key Rules

Pair with other Tenant Portal sections

Summary rules pair with Portal access by tenant category, Bookings > Contract Info, and Settings > General Information (branding). Full pairing matrix: Tenant Portal section cross-reference.

Summary

Access is per-booking. Portal links include booking credentials (typically id + code). Email access-link requests deliver those credentials in a secure link. A tenant with multiple bookings needs separate links/credentials per booking.
Self-service is scoped by settings and booking type. Tenants can view contract, property, and payment information. They cannot change booking dates or the core payment schedule from the portal. Depending on your Preferences, they may update specific profile/billing fields, sign the contract digitally, and pay online when the payment module and property toggles allow it.
Online payments require an active payment module and a property that allows payments. The account must have tenant pay-in provisioned, and Property Payments Active must be on for that listing’s property; otherwise the portal will not complete an online payment.
Branding is account-wide. All tenants see the same brand colour and logo, regardless of which property they are renting.
The portal is white-labelled. It carries your brand identity, not Vivin's — tenants see your company name and colours.
Maintenance requests create tickets automatically. When a tenant submits a request, it appears in the Operations module for your team to manage.

Tenant Portal section cross-reference

Use this table when one portal area naturally leads into operator configuration or a related workflow — each row links to the docs you should read before or after the primary tab.