Skip to content

Payment Reconciliation Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-core-paymentreconciliation
Statusdraft · 1.33.0
BasePaymentReconciliation (constraint)
SourceFSH · 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 identifier as 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