Folio Payments
The payment semantics for hospitality bookings.
What is Folio?
Folio defines the financial terms of a booking—what's owed, when it's due, and what happens if plans change. Where Stay tracks lifecycle states, Folio tracks money.
Hospitality transactions are agreements governing future-conditional payment execution, not immediate exchanges of value. When you book a hotel, you might pay a deposit now, balance at check-in, get a refund if you cancel, or be charged if you don't show up.
Folio is a vocabulary, not a payment processor. It defines how to express hospitality payment terms within existing protocols.
Why Hospitality is Different
| Aspect | Retail | Hospitality |
|---|---|---|
| Payment timing | At purchase | Split across dates |
| Fulfilment | Days after payment | Weeks/months after booking |
| Cancellation | Rarely allowed | Core feature with refund decay |
| No-show | N/A | Triggers penalty charge |
Retail: Intent → Cart → Pay → Ship → Done
Hospitality: Intent → Book → Deposit → [weeks] → Balance → Stay
↓
Cancel? Modify? No-show?
Core Concepts
Payment Schedule
Defines when money moves: deposit at booking, balance before arrival.
Cancellation Policy
Tiered refund decay based on days before check-in.
No-Show Policy
What happens if the guest doesn't arrive.
Modification Policy
Rules for changing dates, rooms, or guests after booking.
Mandate Integration
Cryptographic proof of what the user authorized.
How Agents Use Folio
Check Terms Before Booking
Query the venue's Folio policies to understand payment schedule, cancellation terms, and modification rules before presenting options.
Present Terms Clearly
Ensure the user understands when money will be charged and what happens if plans change before confirming the booking.
Handle Cancellations
Calculate refund amount based on cancellation tier and days before arrival. Execute refund via payment handler.
Process Modifications
Check modification policy, apply any fees, and update the booking. If liability increases, the mandate may need re-signing.
Guest-Owned Records
Folio isn't just venue policy—it's also the guest's record of what happened.
When a stay completes, the guest receives a signed Folio record in their wallet:
Portable
The guest's Folio moves with them. Previous stays at any venue are accessible to their agent for future bookings.
Verifiable
Each Folio is signed by the issuing venue. Agents can verify authenticity without contacting the venue.
Private
Stored in the guest's wallet, shared only with their consent. No central database of travel history.
This is what "guests own their data" means in practice. A guest's booking history, payment records, and stay preferences belong to them—portable across venues, agents, and time.
Commercial Roles
When a guest books through an agent, who is selling? Who is liable?
Merchant of Record
The party who receives payment and appears on the guest's statement. Handles refunds and disputes.
Service Provider
The venue delivering the stay, meal, or experience. Responsible for service quality.
Facilitator
Platform infrastructure connecting parties. Provides tooling without customer-facing liability.
These roles determine:
- Who the guest's contract is with
- Who processes refunds
- Who defends chargebacks
- Who bears consumer protection obligations
Commercial roles are declared, not assumed. A booking must specify who is Merchant of Record so all parties understand the liability chain.
See Settlement Spec for technical details on role declarations and refund authority.