Capturing money is only one step in a financial workflow.
Deciding when ownership should actually change is often the more difficult problem.
For marketplace platforms, payment completion rarely means the recipient should immediately receive the funds.
Reservations can be cancelled.
Events may never happen.
Disputes can arise after payment.
Managers should only receive earnings after the platform determines that settlement conditions have been satisfied.
Those requirements led to one architectural decision.
Money should not move directly from customer payment to manager balance.
Instead, it should pass through an intermediate state.
Escrow became that state.
The Problem
Initially it was tempting to treat a successful payment as a completed transaction.
Once Stripe confirmed payment, the platform could simply credit the manager.
While simple, this introduced several problems.
If a reservation was cancelled before completion, funds had already been transferred.
If a dispute occurred, ownership had already changed.
Refunds became increasingly complicated because multiple balances required correction.
More importantly, the system had no representation of money that had been paid but was not yet earned.
That distinction became essential as the platform matured.
Capturing payment and settling ownership represent different business events.
The platform modeled them independently, allowing funds to remain in escrow until predefined settlement conditions were satisfied.
Escrow as a Domain Concept
Rather than treating escrow as a temporary payment status, it became a dedicated domain model.
Every eligible payment entered escrow immediately after the customer completed payment.
At this stage, the platform acknowledged that money existed, but ownership had not yet transferred.
Conceptually, the lifecycle became:
This separated payment processing from settlement logic.
The application no longer needed to decide ownership during payment processing.
It only needed to record that funds were awaiting settlement.
Delaying Settlement
Escrow introduced time into the financial model.
Funds could remain reserved while the platform waited for business events to complete.
Reservations could reach their scheduled completion.
Private events could conclude successfully.
Dispute windows could expire.
Only after those conditions were satisfied did the platform release funds into the manager's available wallet balance.
Settlement became a business decision rather than an immediate consequence of payment.
Modeling Financial Outcomes
Not every escrow reached the same conclusion.
Some completed successfully.
Others entered disputes.
Some required refunds.
Instead of representing every outcome with generic payment statuses, the platform modeled settlement as explicit financial outcomes.
For example:
- Released
- Refunded
- Forfeited
- Cancelled
Each outcome represented a different business event rather than simply a payment failure.
This made financial history significantly easier to understand because transaction records reflected business intent instead of infrastructure events.
Payment providers describe what happened during payment processing.
The application describes what happened to the money after payment.
Those are different concerns and deserve different models.
Automating Settlement
Escrow also introduced operations that should not block user requests.
Settlement often depended on time rather than immediate user actions.
Instead of requiring administrators to manually review every completed reservation, background workers periodically evaluated escrow records that had become eligible for settlement.
Eligible funds were released automatically.
Managers simply observed their available balance increase once settlement completed.
This kept API requests fast while allowing financial workflows to progress independently.
Keeping Financial History Intact
Escrow also improved financial traceability.
Every monetary event became visible.
Payment.
Escrow creation.
Settlement.
Refund.
Withdrawal.
Instead of overwriting transaction state, the platform preserved each stage of the financial lifecycle.
This created a financial history that was significantly easier to audit and reason about than a single payment record whose status changed over time.
Reducing Feature Complexity
One unexpected advantage of escrow was that product features no longer needed to implement their own settlement logic.
Reservations.
Private events.
Future financial workflows.
Each simply created an escrow record.
The financial subsystem determined when ownership should change.
That reduced duplicated business rules throughout the application while keeping settlement behavior consistent regardless of where funds originated.
Lessons Learned
Initially it seemed natural to credit managers immediately after payment.
After all, the customer had already paid.
The business process, however, was not complete.
Separating payment from settlement allowed the platform to represent financial ownership much more accurately.
Money could exist without immediately belonging to anyone.
That distinction simplified refunds, supported dispute handling, enabled delayed settlement, and provided a much clearer financial model for future product features.
Future Improvements
The current escrow model focuses on time-based and event-driven settlement.
Future enhancements could include:
- Manual settlement review workflows
- Partial escrow releases
- Configurable settlement windows
- Multi-stage settlement approvals
- Automated fraud risk evaluation before release
Because settlement is modeled independently from payment processing, these capabilities can be introduced without changing how payments are collected.
Escrow is often viewed as a payment feature.
In practice, it is a financial ownership model.
Once the platform distinguished between collecting money and transferring ownership, settlement became significantly easier to reason about, while every downstream financial workflow became more predictable and consistent.