Payments & Escrow

Escrow protection, milestone releases, transaction history and a cost breakdown.

<!-- GENERATED FILE. Do not edit by hand. Source: components/help/content/. Run npm run gen:docs. -->

Purpose & Business Context

Payments & Escrow is the trust engine of the platform. Paying a hospital on the other side of the world is the moment a patient feels most exposed, so this screen centres on escrow: money is held and released to the hospital only as each care milestone is verified, with a full pre-arrival refund if the patient cancels.

Commercially, visible escrow protection and transparent, itemised pricing are what make a large cross-border payment feel safe enough to make. The savings panel reinforces the value versus the patient's home market.

Screen Overview

Three stacked rows of cards. The first row pairs the Escrow hero (amount held vs total, with a progress bar) and the protection explainer. The second pairs Payment milestones with the Transaction history ledger. The third pairs the itemised Treatment cost breakdown with the Your savings comparison.

For the demo patient, $8,400 of $14,000 is held in escrow across four milestones, with a deposit already released to Apollo.

Controls & Components

• Escrow hero: amount held vs total, a progress bar, the protection promise, and Add funds and Statement buttons.
• Protection card: four reassurances: milestone release, full pre-arrival refund, transparent pricing and bank-grade security.
• Payment milestones: each milestone with amount and a status badge (Released, In escrow or Scheduled); the held one is highlighted.
• Transaction history: a ledger of charges and releases, with a running 'Currently in escrow' total.
• Treatment cost breakdown: line items grouped by Treatment, Hospital, Travel & stay and Services, ending in an all-in estimate.
• Your savings: the all-in price versus a reference market, a percent saved, and a few home-market comparisons, plus a link to Find Care.

Field Definitions

• Held / Total: Funds currently in escrow versus the total case price (e.g. $8,400 of $14,000); the progress bar shows the ratio.
• Milestone status: Released (paid to the hospital), In escrow (held, releases at a trigger like admission), or Scheduled (a future release).
• Ledger entry: A transaction row: outgoing funds into escrow or charges, and releases to the hospital, with date and amount.
• Cost group: The category a cost line belongs to: Treatment, Hospital, Travel & stay or Services.
• All-in estimate: The sum of every itemised cost line, the transparent total the patient sees.
• Savings %: Approximate saving of the all-in estimate versus the reference home-market list price.

User Actions & Workflows

1. Read the escrow hero to see how much is protected and the promise of milestone-based release.
2. Review the protection card to understand refunds, transparency and security.
3. Scan the milestones to see what has been released and what is still held or scheduled.
4. Open the transaction history to reconcile charges and releases against the 'Currently in escrow' total.
5. Study the cost breakdown and savings, then optionally Add funds, download a Statement, or Compare other clinics.

Navigation & Relationships

Reached from: the sidebar Pay item and the Journey 'Escrow held' status tile.

Leads to: Find Care (/portal/clinics) from the savings card's Compare other clinics link.

Mirrored by: the Journey escrow tile, which summarises the held-versus-total figure shown here.

Business Rules & Constraints

• Funds are released to the hospital only as each care milestone is verified.
• Cancelling before arrival returns the held funds in full (full pre-arrival refund).
• Pricing is fully itemised with no hidden fees; the all-in estimate is the sum of the visible lines.
• Payments are described as PCI-DSS, encrypted and audit-logged (bank-grade security).
• Add funds is simulated in this prototype; it confirms with a toast rather than charging.
• Patient-only screen within the portal.

Data Dependencies

Reads payments (total, held, milestones, ledger) from lib/data, plus the cost breakdown helpers costBreakdownFor('cabg'), breakdownTotal(), savingsPct() and homeMarkets for the savings panel.

• payments: escrow totals, milestones and ledger
• costBreakdownFor('cabg'): itemised cost lines
• breakdownTotal() / savingsPct(): all-in total and savings
• homeMarkets: home-market comparison rows

Error Handling & Edge Cases

• Add funds and Statement are prototype actions that confirm with a toast rather than performing a real transaction.
• If no cost breakdown exists for the procedure, the breakdown and savings cards render nothing rather than erroring.
• The 'Currently in escrow' total always reconciles with the held figure in the hero.
• Mobile: the paired cards stack into a single column while keeping the escrow hero first.

User Roles & Permissions

• Patient: Can view escrow, milestones, ledger, cost breakdown and savings, and trigger prototype Add funds / Statement actions.
• Finance / clinic (out of scope here): Triggers real milestone releases and reconciliations server-side; the patient sees the resulting ledger and statuses.

Related Features & Functionalities

The Journey escrow tile, Find Care (compare clinics on price), the Care Plan (the treatment being paid for), and the corridor model's settlement currency and payment methods. The cost breakdown shares pricing data with the public marketplace.

Flow & Screenshots

flowchart LR
  Pay[Payments & Escrow] --> Escrow[Escrow hero]
  Pay --> Protect[Protection explainer]
  Pay --> Milestones[Payment milestones]
  Pay --> Ledger[Transaction history]
  Pay --> Breakdown[Cost breakdown]
  Pay --> Savings[Your savings]
  Savings -->|Compare other clinics| Find[Find Care]

Guided Walkthrough Steps

The in-app walkthrough for this screen has 6 steps (auto-advances every 5 seconds; Prev / Pause / Next; click outside to exit):

1. Payments & Escrow ([data-tour="nav.pay"])

Where your money is held and protected. You are on the Pay tab now.

1. Your escrow balance ([data-tour="pay.escrow"])

See how much is held versus the total case price. Funds release to the hospital only as each milestone is verified, and you can cancel before arrival for a full refund.

1. How you are protected ([data-tour="pay.protection"])

Milestone releases, a full pre-arrival refund, transparent pricing and bank-grade security, all summarised here.

1. Payment milestones ([data-tour="pay.milestones"])

Each milestone shows its amount and status: Released, In escrow or Scheduled. The held one is highlighted.

1. Transaction history ([data-tour="pay.ledger"])

A clear record of every charge and release, with your current escrow total at the bottom.

1. Itemised cost breakdown ([data-tour="pay.breakdown"])

Every cost grouped by treatment, hospital, travel and services, ending in a transparent all-in estimate.