Verabase System Guide

Appearance

EXCHANGE-CLAIM-01 · Send a hospital claim to an HMO and get the answer back ​

The first cross-organisation exchange: the hospital's Billing Officer sends a submitted claim to a contracted HMO, the HMO's reviewer queries or decides it in their own workspace, and the answer lands back on the same claim — including the payment.

Why this matters ​

Today a claim's "payer" is free text and its answer arrives by email. This journey proves the addressed alternative: the claim travels as a governed work item between two organisations, with an audit trail on both sides, and the hospital sees the HMO's answer in the claims workflow it already uses. It is the first slice of docs/design/exchange-claim-handoff.md; eligibility checks, pre-authorisation and real partner transport come later.

Before you start ​

  • Start the two-tenant walk stack: verabase-client/apps/verabase-tenant-server/src/walk-exchange-server.ts (hospital API :8801, HMO API :8802, sharing the in-process exchange transport) and capture/exchange-walk-stack.sh (facility-web :3210 for the hospital, :3211 for Alpha HMO).
  • The walk seeds its own claim each run: an invoice for a registered patient, a draft claim for Alpha HMO, submitted, with Alpha HMO verified as an exchange partner and a claims-viewer (read-only) user on the HMO side.

Steps ​

  1. The Billing Officer sends the claim. Sign in to the hospital workspace as Bisi Billing (Billing Officer) and open the submitted claim from Claims. The HMO exchange card shows the claim has not been sent. Choose Alpha HMO — only verified partners are offered — and Send claim. The item shows Delivered with the Sent and Delivered events and who sent it.

    Submitted claim before sendClaim delivered to HMO

  2. A duplicate send never duplicates. Sending the same claim version again returns the same exchange item (duplicate: true); the claim still shows exactly one exchange entry. Retry and failure states stay visible on the item instead of silently disappearing.

    Duplicate send never duplicates

  3. The HMO claims officer works the inbox. Sign in to the Alpha HMO workspace as the claims officer and open HMO inbox (Revenue). The claim waits under Awaiting review. Opening it shows the shared claim package — only what the hospital shared: version, invoice, patient identity, priced lines, claimed total. No chart, no unrelated attachments.

    HMO inbox awaiting reviewShared claim package

  4. She asks a question. Decision Ask a question, with the reason the hospital will see. The item records the decision against this claim version — the reason is immutable history.

    HMO queried the claim

  5. The hospital sees the query in claims. Back in the hospital workspace the claim is Queried, with "Their answer" quoting the HMO's reason and the full event trail. The Billing Officer corrects the claim and clicks Resubmit corrected version — a new claim version (v3) goes out as a new exchange item under the same story; the query on v2 stays on record.

    Hospital sees the queryResubmitted version delivered

  6. The HMO approves and pays. The claims officer opens the new version, approves it, and records the payment in the same decision (₦80 of ₦100, reference HMO-PAY-001).

    HMO approved with payment

  7. The hospital reconciles. The claim reads Partially paid, "Payer paid: ₦80 · ref HMO-PAY-001", and the status history carries the remittance. The exchange item shows Approved. Partial, denied and adjusted amounts reconcile against the bill without assuming full payment.

    Hospital claim partially paid

  8. Wrong role sees it read-only. The HMO's claims-viewer can open the inbox and read the item and its recorded decision, but there is no decision form — deciding requires the claims.exchange.decide permission, which this role does not hold. A wrong recipient is refused outright: sending to an organisation without a verified relationship fails (422 EXCHANGE_PARTNER_NOT_FOUND), and the send dialog only ever lists verified partners.

    Wrong role sees no decision form

What this proves ​

  • A claim crosses an organisation boundary as an addressed, audited work item — no cross-tenant database access; the HMO sees only the shared package.
  • Delivery state (sent/delivered/failed) and business decision (queried/approved/denied) are separate facts, and a decision is tied to one claim version.
  • Retries are idempotent; refusals are explicit; both organisations keep an append-only trail.

You're done when… ​

  • The claim shows Delivered on the hospital side with the sent/delivered events, and exactly one exchange item exists after a duplicate send.
  • The HMO inbox held the claim under Awaiting review, and opening it showed the shared package — version, invoice, patient identity, priced lines, claimed total — and nothing beyond it.
  • A query, a resubmission as a new version, and an approval with a partial payment each appeared on the other side against the same claim, ending Partially paid with the payment reference.
  • Signed in as the claims-viewer, the item was readable but no decision form existed.

Practice task ​

Run the walk again (capture/exchange-claim-01.spec.ts against the two-tenant walk stack): send a second claim, deny it on the HMO side, and confirm the hospital claim reads Denied with the reason — then check that the exchange history on the claim still shows every event in order.

Not covered here ​

  • The control plane does not yet carry exchange metadata — this slice runs over the in-process transport between tenants of one deployment (see docs/design/exchange-claim-handoff.md §5). Real partner transport, payload custody and the NDPA review are the next slices.
  • Eligibility checks and pre-authorisation codes are out of scope until a pilot HMO can supply authoritative answers.