Payment Processing

HiLucy processes payments through Stripe, combining secure card vaulting, flexible billing patterns, and Express Checkout to handle everything from single-guest bookings to multi-party group stays.

Card Vault and Tokenization

When a guest checks in or completes a booking, their card is securely saved on file through Stripe's tokenization system:

1. SetupIntent -- Stripe creates a SetupIntent that collects and encrypts the card details
2. PaymentMethod -- The card is tokenized into a reusable PaymentMethod object
3. Card on file -- The PaymentMethod is attached to the guest's profile for the duration of their stay

Card numbers never touch HiLucy's servers. All sensitive payment data is handled entirely by Stripe, keeping your property PCI compliant.

Pre-Authorization Holds

HiLucy uses an authorize-then-void pattern for security deposits:

1. A temporary hold is placed on the guest's card for the configured deposit amount
2. The hold verifies the card is valid and has sufficient funds
3. The authorization is immediately voided -- no charge appears on the guest's statement
4. The card remains on file for potential damage charges or folio settlement

This approach costs the guest nothing while giving your property the security of a verified payment method. See Security Deposits for configuration details.

The Three Payment Patterns

HiLucy's folio system supports three distinct payment patterns that cover every group booking scenario:

Pattern 1 -- Single Payer

One guest provides a card and covers all charges for the entire party. This is the most common pattern for families or corporate bookings.

• Example: A parent pays for spouse and children
• How it works: One card is vaulted, one folio is created, and all charges for all guests route to that single folio
• Charges for minors automatically route to the primary guest's folio

Pattern 2 -- Split (Independent)

Each guest saves their own card and gets their own folio. Charges route to the guest who incurred them.

• Example: Three friends on a trip -- three separate cards, three separate folios
• How it works: Each guest completes the card vault flow via their companion magic link, creating independent payment authorities

Pattern 3 -- Hybrid

A mix of Pattern 1 and Pattern 2. Some guests are covered by another guest's card while others pay independently.

• Example: A parent covers their child, but a traveling friend pays for themselves -- two payment authorities, two folios
• How it works: Each guest is mapped to a payer via the reservation payment authority system. Guests who are "covered" share a folio with their payer; self-paying guests get their own

Multi-Payer Folio System

The folio is an open tab linked to a guest's vaulted card. Here is the full lifecycle:

1. Folio opens -- Created when a guest vaults their card, with an optional configurable hold amount
2. Add items -- Staff add charges throughout the stay: spa treatments, activities, room service, minibar, general charges
3. Void items -- Individual line items can be voided before settlement if added in error
4. Close folio -- Settles all outstanding charges by capturing a Stripe PaymentIntent against the vaulted card
5. Cancel folio -- Releases any hold and closes the folio with no charges captured

Each folio tracks individual line items with category, amount, and status, giving you a complete audit trail.

Express Checkout

HiLucy supports Apple Pay and Google Pay through Stripe's Express Checkout elements. When enabled, guests see Express Checkout buttons on the payment page, allowing them to complete their booking with a single tap using their device's saved payment methods.

Express Checkout uses the same Stripe tokenization pipeline as standard card entry, so all security and PCI compliance guarantees apply.

Payment Flow Summary

| Step | What Happens | Stripe Object | |------|-------------|---------------| | Guest enters card | Card details collected securely | SetupIntent | | Card saved on file | Tokenized for future use | PaymentMethod | | Deposit hold (optional) | Authorize-then-void verification | PaymentIntent (voided) | | Charges added to folio | Staff adds line items | -- | | Folio settlement | All charges captured at once | PaymentIntent (captured) | | Refund (if needed) | Full or partial refund processed | Refund |