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.

FSH

The authored source of truth: resources/StructureDefinition-nexus-core-paymentreconciliation.fsh (edit on GitHub). One FSH file may define several related artifacts.

// StructureDefinition-nexus-core-paymentreconciliation.fsh
//
// One payment or one refund taken at the clinic against invoices raised at the billing vendor --
// the clinic's own record of money in and money back.
//
// WHY THE CLINIC KEEPS THIS RECORD AT ALL. The billing vendor raises and holds private and
// third-party invoices, but its API cannot record a payment against one: the paid amount, the
// payment date and the invoice status are read-only there. Money is still taken at the front
// desk, so the record of it lives here, and the invoices it settles are named by the vendor's
// own invoice identifier rather than by a FHIR `Invoice` this server does not hold.
//
// ONE RESOURCE PER MONEY EVENT. A payment split across three invoices is ONE reconciliation with
// three `detail` entries, because the payer handed over one sum and a receipt names it once. A
// refund is its own reconciliation, never an edit of the payment it returns money from.
//
// REVERSAL IS A STATUS, NEVER A DELETE. A payment keyed against the wrong invoice or the wrong
// amount is reversed by setting `status` to `cancelled` with a reason, and the version history
// keeps both versions. A reversal returns EVERY allocation the reconciliation made; reversing part
// of a split is done by reversing the whole and recording again.
//
// AMOUNTS ARE POSITIVE, ALWAYS. Whether money came in or went back is said by `detail.type`, not
// by a sign, so a sum taken over `paymentAmount` without reading the type is wrong for refunds.
//
// The id takes the bare `nexus-*` form rather than `nexus-emr-*`: new artifacts do not take the
// `-emr-` infix.
//
// ⚠ FIRST PASS -- the payment method set and the reuse of the business identifier as the invoice
// index (see the intro page) are not yet settled. Do not treat either as a contract.

Alias: $NexusCorePaymentReconciliation = https://fhir.apps.health/StructureDefinition/nexus-core-paymentreconciliation

// Every allocation names the invoice it lands on. A detail that names no invoice moves money
// nowhere: no balance can absorb it and no receipt can say what it paid.
Invariant:     nexus-payment-detail-names-invoice
Description:   "Every detail SHALL name the invoice it settles by a billing-vendor invoice identifier"
Severity:      #error
Expression:    "detail.all(request.identifier.where(system = 'https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid' and value.exists()).exists())"

// The index. A reader finds every reconciliation touching an invoice with one token search on
// `identifier`, so an invoice a detail names but the identifier list omits is invisible to it --
// the payment is stored and the invoice still reads as owing.
// Written as all($this in %resource...) rather than subsetOf(): the two agree at the resource root,
// and this form is inside the FHIRPath subset TypedFhir compiles, which every invariant in this guide
// has to be.
Invariant:     nexus-payment-invoices-indexed
Description:   "Every invoice a detail names SHALL also appear in identifier under the same system, so a search by invoice finds the reconciliation"
Severity:      #error
Expression:    "detail.request.identifier.where(system = 'https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid').value.all($this in %resource.identifier.where(system = 'https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid').value)"

// Direction is carried by the detail type, so it has to be one this guide reads.
Invariant:     nexus-payment-detail-kind
Description:   "Every detail SHALL be typed either payment (HL7 payment-type) or refund (Nexus payment-type)"
Severity:      #error
Expression:    "detail.all(type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/payment-type' and code = 'payment') or (system = 'https://fhir.apps.health/CodeSystem/nexus-payment-type' and code = 'refund')).exists())"

// One reconciliation is one event, so it is all money in or all money back. A mix would make
// `paymentAmount` neither a payment nor a refund.
Invariant:     nexus-payment-one-direction
Description:   "A reconciliation SHALL be all payment or all refund, never a mix"
Severity:      #error
Expression:    "detail.where(type.coding.where(system = 'https://fhir.apps.health/CodeSystem/nexus-payment-type' and code = 'refund').exists()).empty() or detail.all(type.coding.where(system = 'https://fhir.apps.health/CodeSystem/nexus-payment-type' and code = 'refund').exists())"

// Positive amounts: the direction lives on the type, never on the sign.
Invariant:     nexus-payment-amounts-positive
Description:   "paymentAmount and every detail amount SHALL be greater than zero; a refund is positive and typed refund"
Severity:      #error
Expression:    "paymentAmount.value > 0 and detail.all(amount.value > 0)"

// A reversal that cannot say why is not auditable, and the office reading the history later has
// nothing to go on.
Invariant:     nexus-payment-reversal-has-reason
Description:   "A cancelled (reversed) reconciliation SHALL carry the payment-reason extension"
Severity:      #error
Expression:    "status = 'cancelled' implies extension('https://fhir.apps.health/StructureDefinition/nexus-payment-reason').exists()"

// Money going back out of the clinic is always explained.
Invariant:     nexus-payment-refund-has-reason
Description:   "A refund SHALL carry the payment-reason extension"
Severity:      #error
Expression:    "detail.type.coding.where(system = 'https://fhir.apps.health/CodeSystem/nexus-payment-type' and code = 'refund').exists() implies extension('https://fhir.apps.health/StructureDefinition/nexus-payment-reason').exists()"

Profile:        NexusCorePaymentReconciliation
Parent:         PaymentReconciliation
Id:             nexus-core-paymentreconciliation
Title:          "Payment Reconciliation Profile"
Description:    "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."
// THE effective date for this profile (see the EffectiveDate / NoEffectiveDate RuleSets): the day
// the money changed hands, not the instant it was keyed.
* insert EffectiveDate([[paymentDate]])

// Closed to SMART applications pending an exposure decision: no smart-exposed declaration, so no
// scope reaches it. A payment ledger is money the clinic took; opening it to a third-party
// application -- and above all opening a write -- is a decision taken for this type on its own.
* ^url = $NexusCorePaymentReconciliation
* ^status = #draft
* obeys nexus-payment-detail-names-invoice
* obeys nexus-payment-invoices-indexed
* obeys nexus-payment-detail-kind
* obeys nexus-payment-one-direction
* obeys nexus-payment-amounts-positive
* obeys nexus-payment-reversal-has-reason
* obeys nexus-payment-refund-has-reason

// --- Element Constraints ---

* . ^short      = "Nexus EMR payment or refund against billing-vendor invoices"
* . ^definition = """
One payment or one refund taken at the clinic, allocated across one or more invoices raised at the
billing vendor. The billing vendor cannot record payments, so this is the clinic's ledger of them;
an invoice's balance is its total less the active payments allocated to it plus the active refunds
allocated to it.
"""
* . ^comment = """
R4 `PaymentReconciliation` was designed for an insurer remitting to a provider. This profile uses
it the other way round -- money taken from a patient or a third party at the clinic -- because it
is the R4 resource whose elements fit: a payment with a date, an amount, an issuer, a reference
number and per-invoice allocations. R5 widened the resource to cover exactly this case, and the
two R5 elements this profile needs (`method`, `enterer`) are carried as R5 cross-version
extensions.
"""

* extension contains
    $xver-paymentreconciliation-method named method 1..1 MS and
    $xver-paymentreconciliation-enterer named enterer 0..1 MS and
    NexusPaymentReason named reason 0..1 MS
* extension[method] ^short = "How the money was paid: cash, debit, credit card, cheque, e-transfer, insurer EFT"
* extension[method] ^definition = "How the money changed hands. The R5 element `PaymentReconciliation.method`, carried as its published R4 cross-version extension."
* extension[method].value[x] from NexusPaymentMethodVS (extensible)
* extension[enterer] ^short = "Who keyed the payment"
* extension[enterer] ^definition = "The person who recorded the payment or refund in the clinic's system. The R5 element `PaymentReconciliation.enterer`, carried as its published R4 cross-version extension. Absent only when the signed-in user cannot be named."
* extension[enterer] ^comment = "Not `requestor`: in R4 that element is the practitioner responsible for the services being paid for, which is a different person from whoever took the money."
* extension[enterer].value[x] only Reference(NexusEmrCorePractitioner or NexusEmrCorePractitionerRole)
* extension[reason] ^short = "Why it was reversed or refunded"
* extension[reason] ^definition = "Why this reconciliation was reversed, or why the refund was given. Required on a cancelled reconciliation and on every refund."

* identifier 1..* MS
* identifier ^short = "The invoices this reconciliation touches, for search"
* identifier ^definition = """
One entry per invoice the reconciliation allocates money to, under
`https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid`, repeating the identifiers on
`detail.request`. It is the index: every reconciliation touching an invoice is found by one token
search on `identifier`, and a reader does not depend on a server supporting the `:identifier`
modifier on `detail.request`.
"""
* identifier ^comment = "This repurposes the business identifier as an index rather than naming the reconciliation itself. Where a server advertises `detail.request:identifier`, that search is the better one, and the mirror may be retired in a later version."

* status MS
* status ^short = "active | cancelled | draft | entered-in-error"
* status ^definition = """
`active` counts toward a balance. `cancelled` is a reversal: the record stays, carrying its reason,
and counts toward nothing. `entered-in-error` is a record that should never have existed and also
counts toward nothing. The clinic does not write `draft`.
"""

* created MS
* created ^short = "When the payment was keyed"
* created ^definition = "The instant the payment or refund was recorded. Distinct from `paymentDate`, the day the money changed hands."

* paymentDate MS
* paymentDate ^short = "The day the money changed hands"
* paymentDate ^definition = "The day the payer paid, or the day the refund was given. This is the effective date: receipts, day-end totals and ageing read it, never `created`."

* paymentAmount MS
* paymentAmount ^short = "The whole amount, always positive"
* paymentAmount ^definition = "The whole sum handed over or returned: equal to the sum of the detail amounts. Always positive -- a refund is told apart by its detail type, not by its sign."
* paymentAmount.value 1..1
* paymentAmount.currency 1..1 MS

* paymentIdentifier MS
* paymentIdentifier ^short = "Cheque number, transaction or e-transfer reference"
* paymentIdentifier ^definition = "The reference the payment instrument carried, when it carried one: a cheque number, a card terminal transaction number, an e-transfer reference."

* paymentIssuer MS
* paymentIssuer ^short = "Who paid"
* paymentIssuer ^definition = "The payer -- the patient, a family member, an employer or an insurer -- as the office named them. Usually a display only: a private payer is seldom a resource the clinic holds."

* requestor ^comment = "Not used by this profile. In R4 this is the practitioner responsible for the services being paid for; who keyed the payment is the `enterer` extension."

* detail 1..* MS
* detail ^short = "One allocation per invoice"
* detail ^definition = "Where the money lands: one entry per invoice, with the amount allocated to it. A payment split across invoices carries one entry for each."
* detail.type MS
* detail.type ^short = "payment | refund"
* detail.type ^definition = "Whether this allocation is money in (`http://terminology.hl7.org/CodeSystem/payment-type#payment`) or money back (`https://fhir.apps.health/CodeSystem/nexus-payment-type#refund`). Every detail in one reconciliation carries the same type."
* detail.request 1..1 MS
* detail.request ^short = "The invoice, by its billing-vendor identifier"
* detail.request ^definition = "The invoice this allocation settles, as a logical reference carrying the billing vendor's invoice identifier under `https://fhir.apps.health/NamingSystem/nexus-clinicaid-invoice-uuid`. The invoice itself is held by the vendor, not by this server."
* detail.date MS
* detail.date ^short = "The day the money changed hands"
* detail.amount 1..1 MS
* detail.amount ^short = "The amount allocated to this invoice, always positive"

* processNote MS
* processNote ^short = "The office's note on the payment"
* processNote ^definition = "Free text the office recorded with the payment. This element, not an extension, is the home for a note on this resource."