Payment Allocation

First-time workspace setup

Read this concept after Getting Started — Recommended Setup Sequence step 5 Invoicing & Payments and your first confirmation receipt in step 14 Bookings. Lifecycle context: Booking Lifecycle. Concept pairing: Concepts — Setup sequence after go-live.

Finding your way in this guide

Understand The Two Layers first, then How Allocation Works and Payment Statuses. Corrections: Correcting mistaken receipts (reject and revert). Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Deposit missing on Finance Deposits, Partly collected security deposit, 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: Payment Allocation section cross-reference · Concepts — Concept cross-reference.

Vivin uses a two-layer payment model to track what tenants owe and what they have paid. Understanding how these layers interact is essential for financial management.

Pair with other concepts

List status filters and Timeline behaviour follow Booking Lifecycle; tenant-initiated payments pair with Tenant Portal (including Portal access by tenant category) and booking-scoped automation in Tenant MCP (get-payment-info); add-on catalogue charges pair with Services Marketplace. Month-end reconciliation pairs with Portfolio KPI review — Step 7 and optional AI usage API (utility_bill_extraction + landlord_chat). Full pairing matrix: Concepts — Concept cross-reference.

The Two Layers

Layer 1: Scheduled Payments (Contract Values)

When a booking is created, the system automatically generates a payment schedule — the complete list of charges the tenant is expected to pay throughout their stay. This includes:

Security Deposit — due at confirmation or check-in
First Month Rent — due at confirmation or check-in
Last Month Rent — due at confirmation or check-in (if configured)
Monthly Rent — recurring charges for each month of the stay
Admin Fee — one-time administrative charge
Cleaning Fee — Every Month (one line per contract month) or a one-time line at booking confirmation or move-in (depending on property settings or the booking's Cleaning Fees requirement on Contract Info)

Each scheduled payment has a type, amount, due date, and status (Pending, Paid, or Overdue).

Business Rule

The payment schedule is fixed at booking creation based on the property's contract settings at that moment. Changing property settings afterward does not affect existing bookings.

Confirmation vs move-in due dates

Layer 1 lines are not all due on the same calendar day. Each booking stores two requirement fields (copied from the property at create time, overridable per booking on Contract Info → Booking information):

Requirement field	Payment-plan flag	Due date rule
Confirmation payments	Booking confirmation	`min(booking created, check-in date)` — late-created reservations do not post confirmation charges after move-in.
Check-in payments	Move-in	The booking’s check-in date (deposit, first rent, last rent, and combinations).

Typical English UI options include Deposit, First rent, Last rent, Deposit and first rent, and Deposit and last rent. The product disables overlapping options across the two dropdowns (for example deposit cannot appear in both buckets).

Booking detail — Contract Info, Confirmation payments and Check-in payments (read-only)

When you change either requirement on an existing booking, Vivin recomputes due dates on flagged lines and may regenerate split rent rows if first or last rent moves between buckets. After Update, open Payment plan and Contract Info → Timeline to confirm due dates and audit log lines. Change unit stays disabled while confirmation payments are still outstanding.

Property defaults are set in Listings — Contract Details. Per-booking overrides and guards are documented in Bookings — Confirmation payments and check-in payments. Bucket pairing matrix: Payment Allocation section cross-reference.

Dual pricing rent split

When a booking is created with dual pricing / local rent cap active, Layer 1 still generates the usual Rent rows, then Vivin splits each primary rent line:

Rent — amount is reduced to min(local rent cap, full rent) for that month.
Others — a companion line for full rent − capped rent, using the Others category configured in Account Settings at booking create.

The split is stored on the booking (useDualPricingRentSplit, localRentCap, dualPricingOthersCategory) and is part of the frozen schedule — it is not recalculated when account settings change later. Operators may update Local Rent Cap on an eligible booking from Contract Info; the API regenerates matching Rent and Others rows.

Allocation and payment priority treat Rent and Others as separate charge types, so partial payments can clear the capped rent portion before the services portion (or vice versa, depending on your priority list).

Layer 2: Incoming Payments (Transactions)

When a tenant actually pays, the payment is recorded as an incoming payment — the real money received. Each incoming payment includes:

Amount received
Payment date
Payment method
Notes (optional)

Incoming payments are recorded in the Finance module or from the booking's Transactions tab.

Adjustments on scheduled lines

Discounts, impairment loss, and (for permitted Vivin internal users) return of value change the net on Layer 1 lines without replacing the payment schedule. Apply discounts and return of value from the booking Contract Values tab; impairment loss is recorded in product data and appears on Payment plan breakdowns. The Payment plan tab reflects updated balances after saves. See Bookings > Contract Values for filters, permissions, and invoicing guards.

Where each layer appears

Scheduled charges (Layer 1) — open a booking and use the Payment plan tab for the schedule view, or Contract Values for the full line ledger (filters, discounts, due-date edits, and invoiced totals). Both reflect the same underlying charges; Contract Values is where operators adjust individual lines.

The Payment plan grid groups charges by due date (one row per date). Rent, Deposit, Others, Total, and Paid are always visible; Cleaning, Admin, and Exit columns appear only when the fee is enabled in Settings → Fees or the booking already stores a non-zero amount for that fee. Total adds only the columns you see plus Deposit — see Schedule table columns and fee visibility.

Booking detail — Payment plan tab showing scheduled charges

Booking detail — Payment plan schedule grid with due-date rows, conditional fee columns, and Total

Incoming payments (Layer 2) — the same booking’s Transactions tab lists money received and how it was allocated. You can also add or adjust payments from Finance.

Booking detail — Transactions tab listing incoming payments and allocations

Recording an incoming payment

From a booking’s Transactions tab, use + Transaction to open Add Payment. Enter the payment date, amount, method, and optional notes, then Submit — the platform allocates the amount to scheduled charges using your payment priority order (see How Allocation Works below). The same modal is available from Create New → Transfer and from Finance.

Add Payment modal from a booking — date, amount, method, and notes before submit

Walkthrough: open an upcoming booking, Transactions → + Transaction, enter a small test amount in Add Payment, submit, then switch to Payment plan to see scheduled charges.

How Allocation Works

When an incoming payment is recorded, the system allocates it to one or more scheduled payments. This is the process of matching real money received to expected charges.

Allocation Priority

The system allocates payments based on the payment priority order configured in Settings > Payments. A typical priority order might be:

Account Settings — Payments tab, Priority Order list (incoming payments apply to charge types top to bottom)

Security Deposit (highest priority)
First Month Rent
Admin Fee
Monthly Rent
Cleaning Fee
Other Charges

When a payment arrives, the system applies it to the highest-priority outstanding charge first, then moves down the list.

Example

A tenant owes: €500 deposit + €400 rent + €100 admin fee = €1,000 total.

The tenant pays €600.

With the priority order above, the system allocates:

€500 → Security Deposit (fully paid)
€100 → First Month Rent (partially paid, €300 remaining)
€0 → Admin Fee (still outstanding)

When the deposit line itself is only partly covered, the booking Deposit tab shows an amber Partially paid badge with a remaining helper (Partial Paid on depositStatus — see Glossary — Deposit lifecycle status). Portfolio triage: Finance → Deposits — Partial paid lifecycle card. Hub matrix: Common Workflows — Partly collected security deposit. Step-by-step: FAQ — Partly collected security deposit (finance-deposits-lifecycle-partial-paid-card.png, finance-deposits-partial-collection-walkthrough.mp4). Distinct from Partial Paid rent rows on Payment Plan — see Handling a Late Payment — Step 1.

Overpayment Handling

If a tenant pays more than the total outstanding amount, the excess is recorded as a credit. This credit is automatically applied to the next charge that becomes due.

Example

A tenant's next scheduled charge is €400 rent. They pay €500.

€400 is allocated to the current month's rent (fully paid)
€100 remains as a credit, applied to the next month's rent when it becomes due

Payment Statuses

Each scheduled payment has one of these statuses:

Status	Meaning
Pending	Charge exists but is not yet due or has not been paid
Paid	An incoming payment has been allocated to this charge
Overdue	The due date has passed and the charge has not been fully paid

Reconciliation

To verify that payments are correctly tracked:

Finance > Overview tab — seven KPI cards for the selected month, stacked Income chart (Paid / Scheduled / In debt), and Debt Aging for receivables triage
Finance > Contract Values tab — lists all scheduled charges and their payment status
Finance > Transactions tab — shows every individual payment received, useful for cross-checking against bank records

Finance — Overview seven KPI cards including Total Debt and Uncovered Debt

Finance — Overview tab with stacked Income chart, Cash flow forecast, and Debt Aging panel

Finance — Contract Values tab listing scheduled charges with type, status, and amounts

If a charge appears in Contract Values but has no matching transaction, the payment has not been received. Month-end drill-down: Portfolio KPI review Step 7 and Payment Allocation section cross-reference.

Key Rules

Summary

Payments are allocated automatically based on the priority order in Settings. You can adjust the allocation if needed.
Overpayments become credits applied to the next outstanding charge.
Partial payments are applied starting from the highest-priority charge. A charge can be partially paid.
Contract values are fixed at booking creation. The schedule reflects the terms in place when the booking was created.
A charge is only "Paid" once allocated. Recording an incoming payment alone is not enough — it must be allocated to a specific scheduled charge.

Correcting mistaken receipts (reject and revert)

Hub matrix: Common Workflows — Reject/revert mistaken receipts. Pair Rent reduction after invoicing when invoiced floor blocks rent cuts — external credit notes then Common Workflows — Bulk Hostkit invoicing Issue credit notes (N) (bookings-rent-reduction-invoiced-floor-flow.mp4). Distinct from duplicate receipt cleanup on Transactions.

Operator-recorded in-payments may stay pending until a user with Approve payments confirms them on Finance → Transactions or the booking Transactions tab. The Overview Manual Payments KPI totals every non-rejected manual receipt in the month — including pending rows — so triage from Finance — Pending manual payments (amber Pending chip on the All type-summary card) or booking Transactions, not the KPI alone. See Glossary — Pending manual in-payment (Finance), FAQ — Manual receipt still pending, and FAQ — Pending manual in-payment on /notifications when the alert persists after row-click triage. When a receipt was entered twice, against the wrong booking, or with the wrong amount:

Symptom	Likely cause	Fix
Duplicate never approved	Still pending	Reject — Pending manual receipt approval
Duplicate after Approve	Wrong booking or amount	Revert payment
Delete payment disabled	vIBAN / invoiced allocation	Revert or Issue credit notes
Red / blue modal	Charge invoiced	Not issued credit note → Issue credit notes (N)

Action	When it applies	Effect in Vivin
Approve payment / Approve selected	Row status pending (or processing)	Confirms the receipt and applies allocations per your payment priority order.
Reject payment / Reject selected	Same pending states	Removes the in-payment from the booking and ledger. On Finance → Transactions, Reject is bulk-only — tick rows and use Reject selected (no per-row reject icon on the ledger).
Revert payment	Status confirmed or rejected	Rolls allocations and booking balances back to the pre-receipt state.

When Finance has already invoiced the charge through your accounting integration, Reject and Revert modals include accounting follow-up copy — a red banner on reject (credit note and invoice follow-up) and a blue info banner on revert. Vivin updates allocations in-product and creates credit-note reversal rows on affected allocations. For integrated invoicing (Hostkit, Invoice-xpress), clear the Not issued credit note queue on Finance → Transactions — filter pill → bulk Issue credit notes (N) or transaction-detail Issue credit note to provider / Set manual — rather than tracking reversals only in a spreadsheet. When accounting runs outside Vivin, you still need manual nota de crédito adjustments; see Glossary — Credit note (payment reject/revert). Reject is also the supported path to clear a provider platform in-payment before Delete Booking on integration reservations (#2076) — see FAQ — Delete Booking on integration reservation. Do not use Delete Booking on the reservation to fix receipt mistakes — that soft-archives the stay and changes ledger visibility (#1897); see FAQ — Cancel Booking vs Delete Booking. After reject/revert, triage not issued credit-note reversals on Finance → Transactions — filter Not issued credit note, then Issue credit notes from the bulk bar or Issue credit note to provider on each allocation in transaction detail. The same invoicing boundary applies when you try to lower rent on Layer 1: invoiced floor (rent) blocks net edits below already-exported totals on Change monthly rent and Contract Values → Edit amount. See Bookings > Transactions row actions, Finance > Row actions, FAQ — Reject or revert an incoming payment, and FAQ — Lower rent below invoiced.

Glossary — Fixed invoice date — Account-wide Invoice date before bulk Issue allocation / Invoice selected; amber banner on Finance → Transactions until you turn Use today as invoice date back on
FAQ — Month-end invoicing (fixed date) hub — Symptom table + toggle reset after batch

Finance Transactions — bulk selection bar with Approve selected and Reject selected

Walkthrough: booking Transactions — open Approve, Reject, and Revert confirmation modals (demo cancels each without saving).

Reject/revert hub matrix: Common Workflows — Reject/revert mistaken receipts.

Finance Transactions — All card with amber Pending chip active and filtered ledger rows

Walkthrough: amber Pending chip on the All card → Approve payment (cancel before saving).

Workflows that routinely approve or reject receipts: Processing a New Booking, Managing a Check-in, Handling a Late Payment, Managing a Check-out — Step 6b, Portfolio KPI review — Step 7, Entering Monthly Utility Bills, and Cancelling a Booking. Reject/revert pairing matrix: Payment Allocation section cross-reference.

Payment Allocation section cross-reference

Use this table when one payment topic naturally leads into operator configuration, a module tab, or a collections workflow — each row links to the docs you should read before or after the primary layer.

| Payment topic | Pair with these docs | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Layer 1 — Scheduled payments | Bookings > Payment plan, Bookings > Contract Values, Listings — Contract Details, API — Creating bookings | | Layer 2 — Incoming payments | Finance > Transactions, Bookings > Transactions, Tenants — With Debt | | Confirmation vs move-in due dates | Bookings — Confirmation and check-in payments, Processing a New Booking, Settings > Preferences | | Dual pricing rent split | Settings > Invoicing — Dual pricing, Bookings > Contract Values | | Allocation priority & overpayments | Settings > Payments priorities, FAQ — Payments & Finance | | Reconciliation | Finance > Overview, Finance > Contract Values, Portfolio KPI review, Portfolio KPI review — Step 6, Finance — Tenant category filter, Bookings — Other filters, Tenants — Tenant category filter, Glossary — Tenant category | | Pending manual approval (month-end habit) | Finance — Pending manual payments, Notification triage — Step 4, Notification triage — Step 5, Portfolio KPI review — Step 7, Processing a New Booking — Step 5b, Handling a Late Payment — Step 4b, Managing a Check-in — Step 3b, Managing a Check-out — Step 6b, Entering Monthly Utility Bills — Step 4b, Cancelling a Booking — Step 2a, Glossary — Pending manual in-payment (Finance), FAQ — Manual receipt still pending, FAQ — Pending manual in-payment on /notifications, Tenant MCP — Property, payments, and portal tools (get-payment-info while receipts stay pending) | | Reject, revert & credit notes | Common Workflows — Reject/revert mistaken receipts, Common Workflows — Pending manual receipt approval, Common Workflows — Rent reduction after invoicing, Finance — Issuing credit notes, Glossary — Credit note, Glossary — Invoiced floor (rent), FAQ — Reject or revert, FAQ — Lower rent below invoiced, Notification triage — Step 4, Portfolio KPI review — Step 7 (bookings-detail-transactions-reject-modal-credit-note-banner.png, bookings-detail-transactions-revert-modal-info-banner.png, finance-transactions-bulk-reject-selected-bar.png, bookings-payment-row-actions-flow.mp4) | | Payment statuses — Overdue | Notifications — Payment overdue alerts, Handling a Late Payment — Step 1, Settings > Payment Delay Penalties, Tenants — With Debt, Finance — Tenant category filter, Bookings — Other filters, Tenants — Tenant category filter, Glossary — Tenant category, FAQ — Finance tenant category filter parity | | Tenant-visible schedule & pay-in | Tenant Portal — Payments tab, Tenant Portal — Make payment (Paywall), Tenant MCP — Property, payments, and portal tools (get-payment-info), Services Marketplace | | Lockout catch-up after password recovery | Sign-in restored; concept validation backlog accumulated | Common Workflows — Lockout catch-up, Getting Started — Lockout catch-up, Resetting a Management User Password — Step 3 | | Pending manual receipt approval | Recorded bank transfers still pending until Approve payments | Common Workflows — Pending manual receipt approval, Finance — Pending manual payments, FAQ — Manual receipt still pending, FAQ — Pending manual in-payment on /notifications, FAQ — Dashboard Total Debt subtitle, Glossary — Pending manual in-payment (Finance), Notification triage — Step 4, Portfolio KPI review — Step 7 | | Reject/revert mistaken receipts | Duplicate or wrong-booking receipts after Approve | Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, Glossary — Credit note (payment reject/revert) | | Portfolio segmentation by tenant category | Review one tenant segment across modules | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Finance — Tenant category filter, Tenants — Tenant category filter | | Notification row-click navigation | Layer 2 Transactions after /notifications row-click | Concepts — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Two-layer ledger behind payment overdue alerts | Concepts — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Layer 1 schedule lines on Upcoming bookings | Concepts — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Month-end AI cost review | Portfolio KPI review — Step 7, AI usage API (utility_bill_extraction + landlord_chat) |