Payment Reconciliation Profile¶
| Canonical | https://fhir.apps.health/StructureDefinition/nexus-core-paymentreconciliation |
|---|---|
| Status | draft · 1.33.0 |
| Base | PaymentReconciliation (constraint) |
| Source | FSH · JSON |
Defines the Nexus EMR FHIR profile for a payment or refund taken at the clinic against private and third-party invoices raised at the billing vendor. One reconciliation per money event: a payment split across several invoices is one reconciliation with one detail per invoice. Invoices are named by the billing vendor's invoice identifier. Amounts are always positive; the detail type says whether money came in or went back. A reversal sets status to cancelled with a reason and keeps the record.
Overview
⚠ FIRST PASS -- do not treat this as a contract. The payment method set and the use of
identifieras the invoice index below are not yet settled.
Overview
A clinic takes money at the front desk against private and third-party invoices -- an uninsured service, a form, a missed-appointment fee. Those invoices are raised and held at the billing vendor, whose API cannot record a payment against one. This profile is the clinic's own record of each payment and refund, keyed to the vendor's invoices by their identifier.
One reconciliation per money event. A payer who settles two invoices with one debit payment
produces one reconciliation with two detail entries -- one sum handed over, one receipt, two
allocations. A refund is its own reconciliation.
An invoice's balance is its total, less the active payments allocated to it, plus the active refunds allocated to it.
How each fact is carried
| Fact | Element |
|---|---|
| The day the money changed hands | paymentDate (the effective date) |
| When it was keyed | created |
| Who keyed it | R5 cross-version extension extension-PaymentReconciliation.enterer |
| How it was paid | R5 cross-version extension extension-PaymentReconciliation.method, from Payment Method |
| Cheque number or transaction reference | paymentIdentifier |
| Who paid | paymentIssuer.display |
| Each invoice and the amount allocated to it | detail.request.identifier, detail.amount |
| Money in, or money back | detail.type |
| The office's note | processNote |
| Why it was reversed or refunded | nexus-payment-reason |
R4 PaymentReconciliation was shaped for an insurer remitting to a provider. R5 widened it to cover
a payment taken at the point of service and added method and enterer for it. Those two are
carried here as HL7's published R4 cross-version extensions, so a reader migrating to R5 finds them
where R5 puts them.
Payment or refund: the type, never the sign
detail.type says which way the money moved:
- money in --
http://terminology.hl7.org/CodeSystem/payment-type#payment, HL7's own code; - money back --
https://fhir.apps.health/CodeSystem/nexus-payment-type#refund, minted here because HL7's payment-type system has no refund concept.
Every amount is positive, refunds included. A report that sums paymentAmount without reading
detail.type counts each refund as money in. One reconciliation is all payment or all refund; the
profile refuses a mix.
Reversal
A payment keyed against the wrong invoice or for the wrong amount is reversed, never deleted:
the reconciliation is updated to status = cancelled with a
reason, and the version history keeps both
versions. A cancelled reconciliation stays readable and counts toward no balance.
A reversal returns every allocation. A split payment is reversed as a unit, because the payer handed over one sum. To move part of a split to another invoice, reverse it and record the payment again with the right allocation.
Write the reversal conditionally on the version read (If-Match), so two people reversing the same
payment cannot both succeed.
Finding the payments on an invoice
Each invoice a reconciliation allocates to is named twice: on detail.request.identifier, where R4
intends it, and again in identifier, under the same
ClinicAid invoice system. Every reconciliation
touching an invoice is then one token search:
GET [base]/PaymentReconciliation?identifier=https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid|<invoice uuid>
This uses identifier as an index rather than as the reconciliation's own business identifier.
It is done so that a reader does not depend on a server supporting the :identifier modifier on a
reference search. Where a server advertises detail.request:identifier, that search is the better
one, and the mirror may be retired in a later version. The profile requires every invoice a detail names to appear in identifier.
Terminology bindings
| Path | Strength | Value set |
|---|---|---|
PaymentReconciliation.extension.value[x] |
extensible | Payment Method Value Set |