Payments & folios

Payments & Invoices is the money side of a stay. Every booking that is confirmed or checked in has an invoice, the folio: that collects room nights, taxes, deposits, fees and restaurant charges. This screen lists those invoices, shows what has been paid, lets you record a payment or a refund, and prints or emails the invoice.

There is no card gateway: the system records money that has already changed hands (cash, mobile money, card terminal slip, bank transfer) and keeps the reference you type. Amounts are whole shillings, the hotel currency label can change in Settings, but there are never decimals.

Receptionists can open the screen and read every folio; recording money needs Payments at Can edit (Accountant, Hotel Manager, Restaurant Manager by default) and refunds need Full.

The folio drawer

Clicking a row opens a drawer titled with the invoice code (e.g. INV-0412) and the guest and booking under it. Left: status badge, issued and due tags, the line items (Item · Qty · Amount) and a dark totals card (Total · Paid · Balance). Right: the Payment history: one entry per payment or refund with method, network, reference, code, date and who received it. Footer buttons: Close,Print, Email, Record payment (only while a balance is owed) and, once the payment form is open, Save payment.

Empty state: “No invoices yet. A folio opens at check-in, and a deposit invoice when a booking is confirmed”.

An invoice is a header (issue date, due date, totals, a cached status) plus lines of a kind:room, tax, deposit, fee, pos,adjustment, other. Where each comes from:

1. 1
   Confirmation, deposit invoice

   If the hotel has a deposit % (Settings → Hotel), confirming a booking opens an invoice with one line “Deposit <pct>% · BK-…”. Issue and due date are the hotel-local day it was raised. The guest can pay it now; it shows as Pending, Partially Paid or Paid like any other.
2. 2
   Check-in, the stay lands on the same invoice

   Check-in appends “Accommodation · BK-… · <room type> × N nights” and the tax lines “Service charge X%”, “VAT X%”, “Tourism levy X%” (only those with a non-zero rate). If a deposit invoice already exists it is reused: every deposit line is offset by an equal negative line “Deposit applied to stay · BK-…”, so total = the stay, and whatever was paid on the deposit already counts toward it. The deposit is never charged twice.
3. 3
   During the stay, POS room charges

   A restaurant or bar ticket closed with Charge to Room posts “POS · TKT-… · <outlet>”, “Service charge · TKT-…” and “VAT · TKT-…” lines onto the open folio and raises its total. A folio that was already Paid becomes Partially Paid again.
4. 4
   Cancellation / no-show, fees

   A cancellation fee (% of the stay) or no-show fee (% of one night), if configured, is added as a fee line, on the open invoice if there is one, otherwise a new one. Each fee posts once per booking.
5. 5
   Check-out, the folio closes

   Check-out closes every open invoice on the booking: no more charges can land on it, but it stays payable until settled.

The tax chain

Totals are computed in one fixed order and rounded at every step: discount on the subtotal → service charge on the discounted subtotal → VAT on (discounted subtotal + service) → tourism levy on the discounted subtotal → total. Rates are the hotel's percentages in Settings; a POS outlet may override the service % for its own tickets.

1. 1
   Open the folio

   Click the invoice row. Check the Balance figure in the dark card, that is what can be collected.
2. 2
   Click Record payment

   The button is in the drawer footer and only shows while the balance is above zero. The Amount field is pre-filled with the full balance.
3. 3
   Enter the amount

   Whole shillings only; commas and spaces are stripped. A part-payment is fine, the invoice becomes Partially Paid and Record payment stays available for the rest.
4. 4
   Choose the method

   Cash · Mobile Money · Card · Bank Transfer. Mobile Money asks for the Network (MTN or AIRTEL). Every method except Cash shows a Reference no. field (“Transaction / slip reference”), type the MoMo transaction id, card auth code or transfer reference so the audit trail can be matched to the bank.
5. 5
   Save payment

   A PAY-… code is issued, the invoice status is re-derived, a notification is raised (“Payment received on INV-…” or “Invoice INV-… settled”) and the toast reads “Payment of UGX … recorded on INV-…”.

A refund is a payment entry with a negative effect, linked to the payment it reverses. It cannot exceed what is still refundable on that payment, nor what has been collected on the invoice overall.

1. 1
   Find the payment in Payment history

   Each non-refund entry with something left shows a Refund chip; if part of it was already returned the chip reads Refund rest. A fully returned payment shows a Refunded badge instead.
2. 2
   Click Refund

   A confirm dialog titled “Refund PAY-…?” explains: “This refunds whatever is still outstanding on the payment. The guest balance will increase.”
3. 3
   Issue refund

   The refund is created with the same method and reference as the original, a new PAY-… code, written to the audit log as payment.refunded, and the folio status is re-derived (Refunded once net paid reaches zero).

The rule lives on the booking, but it is a payments rule: Check out on the booking drawer refuses while any open folio on that booking has a balance. The 409 names the invoices and the total , “INV-0412 still owes UGX 240,000. Collect it before check-out, or a Payments manager can check out and bill later”.

1. 1
   Usual path, collect first

   Open Payments, record the balance, then check the guest out. The folio is closed at check-out and shows Paid.
2. 2
   Exception, settle later

   Bill-to-company or a disputed charge: a user with Payments Full sees a confirm on the booking drawer to check out anyway. The booking is checked out, the action is audited as booking.checkedout_unsettled, and the folio is closed to new charges but stays open for collection here.
3. 3
   Collect afterwards

   The invoice keeps its status (Pending, Partially Paid, and Overdue once the due date passes). Record payment works exactly as during the stay.

• Pending: nothing received yet.
• Partially Paid: net paid (payments minus refunds) is above zero but below the total.
• Paid: net paid ≥ total.
• Refunded: at least one refund exists and net paid is back at zero or below.
• Overdue: Pending or Partially Paid and the due date is before the hotel's today. This one is derived on every read: list, drawer, PDF, search, the booking drawer and the night audit, and is never written to the database.

• Open the list, open a folio, Print (PDF): Payments · View only.
• Record payment, Email invoice: Payments · Can edit.
• Refund: Payments · Full access.
• Check out with a balance (settle later): Payments · Full access, from the booking drawer (Bookings · Can edit for the check-out itself).

The POS terminal, Restaurant and Inventory share the Payments module, so a Restaurant Manager (Can edit) can record a folio payment here even though their day is spent on tickets.

Folio

The invoice attached to a booking that collects the stay, taxes, deposits, fees and POS charges. Opens at confirmation (deposit) or check-in; closes at check-out.

Deposit

A percentage of the stay requested at confirmation as a deposit line. At check-in it is offset by an equal “Deposit applied” credit so it is never charged twice.

Net paid

Payments minus refunds on an invoice.

Balance

Total minus net paid, never below zero.

Overdue

Derived: unpaid or part-paid and due before the hotel’s today. Never stored.

Settle later

A Payments-Full override that checks a guest out with a balance; audited; the folio stays collectable.