Skip to main content

Payment Allocation

Ask AI Chat “Where do I open Finance and the booking Payment plan to review payment allocation — scheduled charges, incoming receipts, Approve payment, and how Layer 1 Contract Values match Layer 2 payments (not Account Settings Payments due days, and not Tax Codes)? Name the screens — product navigation only, no account data.” — then open Business → Finance and the booking Payment plan (ai-chat-product-context-payment-allocation-reply.png, ai-chat-product-context-payment-allocation-flow.mp4). The assistant typically points at Finance tabs (Overview, Contract Values, Transactions, Payments, Deposits) plus Bookings → Payment plan for the per-reservation schedule. Same grounding external MCP clients get from get-vivin-context-finance. Distinct from due-day rules on Settings → Payments and from Tax Codes.

AI Assistant — where to open Finance and the booking Payment plan for payment allocation

Walkthrough: ask AI Assistant where to review payment allocation on Finance and the booking Payment plan, then open Business → Finance and Bookings → Payment plan.
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). Habit-specific shortcuts live under Related below.

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).

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 fieldPayment-plan flagDue date rule
Confirmation paymentsBooking confirmationmin(booking created, check-in date) — late-created reservations do not post confirmation charges after move-in.
Check-in paymentsMove-inThe 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:

  1. Rent — amount is reduced to min(local rent cap, full rent) for that month.
  2. 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. Partner listing JSON does not include the cap — advertised rent is the full monthly amount — Listings & Availability — Local rent cap.

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 roles with bookings.add_return_of_value) 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. Return of value only reverses not-invoiced cash — invoiced / manual / draft parents are disabled in the modal; use a credit note for those. The Payment plan tab reflects updated balances after saves. See Bookings > Contract Values for filters, permissions, and invoicing guards (bookings-detail-contract-values-manage-return-of-value-protected.png, bookings-detail-contract-values-manage-return-of-value-draft-caption.png, bookings-detail-contract-values-return-of-value-flow.mp4, bookings-detail-contract-values-return-of-value-draft-caption-flow.mp4).

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, plus negative return of value rows so money handed back is visible next to receipts. 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)

  1. Security Deposit (highest priority)
  2. First Month Rent
  3. Admin Fee
  4. Monthly Rent
  5. Cleaning Fee
  6. 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:

StatusMeaning
PendingCharge exists but is not yet due or has not been paid
PaidAn incoming payment has been allocated to this charge
OverdueThe due date has passed and the charge has not been fully paid

Reconciliation​

To verify that payments are correctly tracked:

  1. Finance > Overview tab — seven KPI cards for the selected month, stacked Income chart (Paid / Scheduled / In debt), and Debt Aging for receivables triage
  2. Finance > Contract Values tab — lists all scheduled charges and their payment status
  3. 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

  1. Payments are allocated automatically based on the priority order in Settings. You can adjust the allocation if needed.

  2. Overpayments become credits applied to the next outstanding charge.

  3. Partial payments are applied starting from the highest-priority charge. A charge can be partially paid.

  4. Contract values are fixed at booking creation. The schedule reflects the terms in place when the booking was created.

  5. 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 (typo on a real transfer vs a duplicate):

SymptomLikely causeFix
Duplicate never approvedStill pendingReject — Pending manual receipt approval
Typed the wrong €, still pendingReal transfer; amount typoEdit payment amount then Approve — Bookings — Edit payment amount
Duplicate after ApproveWrong booking or amountRevert payment
Delete payment disabledvIBAN / invoiced allocationRevert or Issue credit notes
Red / blue modalCharge invoicedNot issued credit note → Issue credit notes (N)
ActionWhen it appliesEffect in Vivin
Approve payment / Approve selectedRow status pending (or processing)Confirms the receipt and applies allocations per your payment priority order.
Edit payment amountPending manual in-payment (not vIBAN / card); Approve paymentsUpdates the received € before Approve. Booking sidebar: Edit Payment Amount modal. Finance ledger: inline Amount cell (Enter / blur save; Escape cancel). Distinct from Contract Values → Edit amount.
Reject payment / Reject selectedSame pending statesRemoves 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 paymentStatus confirmed or rejectedRolls 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 — 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; 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.

Booking detail Transactions — Reject payment confirmation with red credit-note warning banner

Booking detail Transactions — Revert payment confirmation with blue invoice follow-up info banner

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 the sections above for this concept. Related module and workflow pages are linked inline where they help the next step.

Pair with other Payment Allocation guide sections

Related below links this concept to modules, workflows, settings, and escalation paths.

Documentation map & escalation​

  • Introduction — Platform overview and how documentation sections connect
  • Getting Started — Recommended setup sequence including payment priorities and deposit rules
  • Concepts — Underlying models behind Layer 1 schedules and Layer 2 receipts
  • Modules — Operator workspaces for Bookings, Finance, and Tenants
  • Common Workflows — Procedures that record, approve, and reconcile payments
  • Account Settings — Workspace-wide financial policies, templates, and integrations
  • API Reference — Partner imports that create the same schedule operators see in the UI
  • Glossary — Term definitions used across payment docs
  • FAQ & Troubleshooting — Quick answers when allocations disagree with bank records
  • Get Help & Support — Escalation when payment behaviour is blocked by account state
  • Using in-app support — Vivin product tickets distinct from tenant payment disputes

Navigation & bookmarks​

Pair with other Payment Allocation guide sections

Bookmark routes pair with Management Frontend Deep Links and Concepts hub — Navigation & bookmarks.

Layer 1 schedule and property defaults​

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Layer 2 receipts, approval, and corrections​

Lockout catch-up after password recovery​

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​

Collections and month-end workflows​

Deeper workflow reads​

Pair with other Payment Allocation guide sections

Common Workflows — Reject/revert mistaken receipts. Each workflow sub-guide reciprocates with [Deeper workflow reads](../concepts/payment-allocation.md#deeper-workflow-reads) anchors on Payment Allocation bullets —

Deeper concept reads​

Deeper API reads​

Key glossary terms​

Module documentation hubs​

  • Finance module — Portfolio ledgers (Overview, Income, Contract Values, Transactions, Payouts, Deposits) with payment approval and deposit settlement (hub)
  • Bookings module — Payment plan, Contract Values, Transactions, and Deposit tabs on one reservation (hub)
  • Tenants module — Tenant directory, With Debt segmentation, and profile Transactions (hub)
  • Utilities module — Bills Included ceiling model and tenant overage charges on payment plans (hub)
  • Operations module — Ticket linked cash flows that may post contractor receipts (hub)
  • Dashboard module — Total debt KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range Revenue charts for receivables context (hub)
  • Listings module — Property wizard defaults that freeze Layer 1 at booking create (hub)
  • Sales module — Pricing monthly rent grid distinct from per-booking Contract Values (hub)
  • Inbox module — WhatsApp triage when tenants dispute charges outside Finance (hub)
  • Notifications module — Full /notifications history with payment alert row-click navigation (hub)
  • Notifications — Payment overdue alerts — Operator Payments category rows when Layer 1 lines pass due date without full allocation (hub)
  • AI Chat module — AI Assistant for portfolio payment Q&A (hub)
  • Audit module — Portfolio-wide Discounts contract-value review (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)
  • API Reference hub — Partner HTTP contracts, Swagger onboarding, and partial vs full feeds (hub)