Booking Deposits

A deposit or the whole price paid online when a client books: the time waits for the payment, the staff hear of the booking once it is paid, and the money is refunded or kept by the rules the client was shown.

kitloom/booking-deposits · admins: kitloom/booking-deposits-filament, kitloom/booking-deposits-nova

A deposit, or the whole price, paid online when a client books. The time the client chose waits for the money; once it is in, the booking is made as it would be without a deposit, and the staff member hears of it. Unpaid in time, the time is free again. The money follows the booking by rules the client is shown: refunded when the salon declines or cancels and when the client cancels in time, kept on a no-show. The payment goes through the site's own payment methods (kitloom/payments: Stripe, PayPal, Mollie, Square and the rest). The admin is kitloom/booking-deposits-filament or kitloom/booking-deposits-nova.

Before you start

A deposit is paid online, so the site needs a payment method that is switched on under Payments and takes the bookings' currency (Bookings → Settings → Currency). A bank transfer or cash does not count: neither says within minutes that the money is in. While no method fits, no deposit is asked and clients book as before; the Settings page says so at the top.

Choose what the services ask

Booking Deposits → Settings, under What a client pays when booking:

• Every service — what each service asks unless it has its own:
  • None — no deposit;
  • A fixed amount — the amount below (20.00), never more than the service's price;
  • A share of the price — the percent below (30) of the price the client books at, the staff member's own price included;
  • The whole price — the client pays it all when booking.
• Amount or percent — for a fixed amount or a share.
• Services with a deposit of their own — a row per service that asks something else: None for a quick trim when every service asks 30 %, A share of the price for colour and balayage when the rest ask nothing. A service without a row asks the default.

Only bookings made on the site pay. A booking made in the admin, or by an AI agent, asks nothing: the salon takes those itself.

What the client sees

1. The booking form shows the deposit next to the price ("€25.50 now") and, on the last step, how much is paid now and how much at the visit, and the ways to pay when there are several. The button says Book and pay.
2. The time is held and the client is sent to the payment page. Back from it, they land on their booking's page: paid, or still waiting for the payment service's word.
3. Closed the tab? The booking's page (from the account's Appointments, Pay now) has the Pay now button until the time is let go.
4. Paid, the booking is made: the client gets the usual "we will confirm" or "confirmed" email, with the deposit and what is left to pay at the visit.

Until it is paid, the booking says Waiting for payment. It holds its time — nobody else can book it — but nobody hears of it: no email to the staff member, no notice to the owner, no Google Calendar event, no Zoom meeting, no webhook. All of them come once the money is in, as they would when the client pressed Book.

When the money does not come

Minutes to pay (30) under Paying and getting it back is how long the time waits. Unpaid by then, the booking is let go — cancelled, Not paid in time — and the client gets an email with a link to book again. The scheduler does it every minute, so the site needs schedule:run in its cron (see the deployment guide).

A payment that arrives after the time was let go (the client paid at the last second, the payment service answered late) brings the booking back if its time is still free. Taken by someone else meanwhile, the money is refunded and the client told why.

When the booking ends

What happens to the booking	The deposit
The salon declines it	refunded
The salon cancels it	refunded
The client cancels in time (the bookings' cancelling limit, 12 hours by default)	refunded — or kept, with Refund when the client cancels in time off
A no-show	kept
Done	kept: it counts toward the price
Moved, by the client or the salon	stays with the booking

A client cannot cancel online after the cancelling limit, so a late cancel is a call to the salon, which decides.

A refund goes back through the payment service the client paid with, from the queue, and the client gets an email. A payment service that cannot refund from the site leaves a note on the deposit: give the money back in its own dashboard, then Mark refunded.

Deposits

Booking Deposits → Deposits lists every deposit, newest first: the booking and the client, the service and when, the amount and the price, where it stands — To pay, Paid, Not paid (let go), Refunded, Kept — the booking's own status and a note when a refund needs doing by hand. A paid deposit has three actions:

• Refund — the money goes back through the payment service now and the client gets an email. The booking stays as it is.
• Mark refunded — for money given back in the payment service's dashboard: the deposit says refunded and the client gets an email.
• Keep — the deposit stays with the salon when the booking ends.

The payments themselves are on the Payments screen, with the gateway's reference.

Settings

Booking Deposits → Settings:

• Every service (none), Amount or percent (0) and Services with a deposit of their own.
• Minutes to pay (30, from 5 to 1440).
• Ways to pay (none chosen — every online method that takes the currency).
• Refund when the client cancels in time (on).

Beyond the screens

• AI agents (kitloom/ai), for whoever has the permission: booking_deposits_list — the deposits by booking code or status ("Did Ada pay her deposit for Tuesday?"), and the rules in describe_site. Refunds and the rules stay in the admin.
• A theme: the booking part gives each service's deposit (and each staff member's for their own price) and the ways to pay in rules.payMethods; the form sends method, and the answer's payUrl is where the client goes next. Atelier draws it all.

What is inside

What	Where
Deposits	table booking_deposits (the site's prefix in front), one row per booking, model Kitloom\BookingDeposits\Models\Deposit — what kitloom/payments charges
Services' own rules	table booking_deposit_rules, model Kitloom\BookingDeposits\Models\DepositRule, written whole by RuleWriter
Settings	options booking_deposits_*: the default rule, the minutes to pay, the ways to pay, the refund on a cancel in time
Permission	manage_booking_deposits, given to the roles that manage bookings
Scheduler	booking-deposits:release, every minute
Configuration	config/kitloom-booking-deposits.php

The module binds kitloom/bookings' Prepayment contract: the bookings ask it what a service costs up front, keep a booking Waiting for payment while it holds the deposit, and print its lines on the booking's pages and emails. It hears of the payment through kitloom/payments (Payable::paid()) and of the booking's end through the bookings' events.

What the application overrides

• The models: ModelRegistry::use(Deposit::KEY, App\Models\Deposit::class) and the same for DepositRule::KEY.
• The queue of the refunds, the admin sections and the agent tools: php artisan vendor:publish --tag=kitloom-booking-deposits-config.

Tests

From the application that installs the package: php vendor/bin/phpunit --testsuite BookingDeposits. The tests pay through kitloom/payments' fake gateway (Kitloom\Payments\Testing\FakePayments).