What the rail absorbs
Every response tells you what to call next. You read the sequence off the responses instead of working it out yourself.
That is most of the design. The rest of this page fills it in.
The trade
You keep your system. You keep your clinical workflow, your screens, your data model, your release schedule. What you give up is having to know which payer world you are in.
You get one base URL, one identity vocabulary, one benefit shape, one consent flow, one claim lifecycle and one remittance contract. Behind that, the public and private worlds still differ as much as they ever did. The rail absorbs the difference rather than forwarding it to you.
What stops being yours
Resolving identity across registries. You send an identifier and its type, and you get
back a unique_patient_id. Everything after that keys off that one value: cover selection,
eligibility, authorisation, preauthorisation, reservation, billing and claims, whichever
payer ends up being billed. You never maintain a mapping table between identity systems,
because you only ever see one.
Normalising benefits. Public benefit trees and private benefit trees nest differently and terminate in different vocabularies. What you receive is one benefit shape, with a pointer to where its billable units live. The units underneath vary; the envelope around them stays the same.
Every mode of consent, and the rules that decide between them. Fingerprint, face, one-time code, guardian and national eKYC, each with its own vendor and device, plus the payer-specific rules for who may use which, which change without notice. Whether this member can use OTP, whether biometrics is enforced at this facility, whether a guardian is required because the member is a minor, whether a card-less path applies: all of that resolves through a decision tree fed by the member, the facility, the payer and the benefit. You do not implement that tree. You render what you are handed.
Knowing which network you are on. A payer is not a single set of mechanics. It reaches you through a network, and it is the network, not the payer and not the scheme name on the card, that decides how a member is identified, how eligibility is checked, which authorisation modes are permitted, and how a finished claim is dispatched. Worse, the binding sits at scheme level, so one insurer can span several networks, and you have to know the network early in the visit or half the screens that follow are wrong. Off the rail, that is a resolution step you own and a set of branches you maintain. On it, the network is resolved when identity is, and never appears in your code.
Knowing where a claim goes. There is one close endpoint. The dispatch decision was made back at cover selection and has been carried on every line since, so you never pick a different endpoint per payer.
The error taxonomy. One error shape: error, message, path, fix_stage. Validation
returns every reason at once instead of one at a time, so you fix the whole batch in a
single round instead of queueing up repeat attempts.
What stays yours
The rail does not make clinical judgements, and it does not pretend to.
Your system knows what clinical data belongs to a benefit type, and your system populates it. The rail's job is narrower. Before anything is accepted, it checks that everything the chosen benefit type requires on the current payer is present and well-formed, and if something is missing it rejects with a message naming what is missing, rather than passing something half-formed downstream.
Pricing, coding, care decisions and the record of what happened to the patient stay yours. The rail carries them without authoring them.
Where the differences went
The differences did not disappear. They moved.
Where payers genuinely behave differently, the rail surfaces that in place, inside the single flow, at the moment it matters: one payer holds money against a benefit in real time while the other tracks balance externally; one routes clinical sign-off through a separate review product; one auto-reserves on approval while the other expects an explicit call. Where you need to know, you are told, on the page you are already on.
What you are never asked to do is choose a branch before you can start learning. There is no public track and no private track. There is one journey, and the variance sits inside it as a footnote.
The sequence
The whole surface is one sequence, and every scenario is this sequence with different values in it:
There are two reorderings. Elective care moves preauthorisation before the visit. Emergency reverses the first two steps, because treatment starts before anyone has established who is being treated.
Learn the sequence once and every shape follows from it.
How you are told what to do next
Every response carries next_action. Its type names the move, and where a call is
required it carries the endpoint too:
Code
A client that switches on this one enum can drive the entire flow without any chapter-specific logic, which is the point. The client is told its next move rather than inferring it.
What good looks like
You can tell this is working less from how quickly the integration went than from where a refusal lands. It should happen at the front desk, in front of the patient, while it can still be fixed, instead of arriving as a rejected claim a week later, when the patient has gone home and the money has not.
Next: Benefit coordination · or skip ahead and start integrating.