Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:12:32Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:42, 6 July 2026
Line 280:		Line 280:
	* Send <code>tendered_amount</code> and <code>returned_amount</code> (both required); the server derives <code>amount</code>, so any value you send for it is ignored.		* Send <code>tendered_amount</code> and <code>returned_amount</code> (both required); the server derives <code>amount</code>, so any value you send for it is ignored.
	* <code>extensions</code> holds custom key-value data without a schema migration, validated against registered handlers.		* <code>extensions</code> holds custom key-value data without a schema migration, validated against registered handlers.

			{{Navbox billing}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:44:13Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=billing
|title=Payment Reconciliation
|order=5
|introduced=3.0
|model=PaymentReconciliation
|reference=References/Base models & conventions
}}

A <code>PaymentReconciliation</code> is a single payment recorded against an <code>Account</code>, and optionally allocated to one <code>Invoice</code>. It captures how much was paid, by what method, when, and by whom — mirroring the FHIR [<nowiki/>https://build.fhir.org/paymentreconciliation.html <code>PaymentReconciliation</code>] resource. Reach for it whenever you post a payment, refund, credit note, or adjustment to a patient or insurer account.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/payment_reconciliation.py <code>care/emr/models/payment_reconciliation.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/payment_reconciliation/spec.py <code>care/emr/resources/payment_reconciliation/spec.py</code>]

The model is thin storage: enum-constrained fields are plain <code>CharField</code>s and <code>extensions</code> is an opaque <code>JSONField</code>. The behaviour you integrate against — enum constraints, amount computation, validation, and the read/write schema split — lives in the Pydantic resource specs (<code>care/emr/resources/payment_reconciliation/spec.py</code>), built on <code>EMRResource</code>.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>PaymentReconciliation</code>
| A single payment (or credit note / adjustment) recorded against an account or invoice
|}

The model extends <code>EMRBaseModel</code>, the shared Care EMR base supplying <code>external_id</code>, audit fields, and soft-delete semantics — see [[References/Base models & conventions|Base model]].

== <code>PaymentReconciliation</code> fields ==

=== Relationships ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=PaymentReconciliation|section=Relationships|name=facility|type=FK → Facility (PROTECT)|notes=Facility where the payment is recorded}}
{{Field|model=PaymentReconciliation|section=Relationships|name=target_invoice|type=FK → Invoice (PROTECT)|notes=The invoice this payment is allocated to. Nullable (<code>default=None</code>); one allocation per record. On write, pass the invoice <code>external_id</code> (UUID)}}
{{Field|model=PaymentReconciliation|section=Relationships|name=account|type=FK → Account (PROTECT)|notes=The account being paid. Required even when <code>target_invoice</code> is set. On write, pass the account <code>external_id</code> (UUID)}}
{{Field|model=PaymentReconciliation|section=Relationships|name=location|type=FK → FacilityLocation (PROTECT)|notes=Physical location (e.g. the counter) where payment was taken. Nullable. On write, pass the location <code>external_id</code> (UUID)}}
|}

=== Classification ===

Six columns map to fixed enums defined in the resource spec. Each is stored as a free-form <code>CharField(100)</code>; the enum is enforced at the schema/API layer, not by the database. Full value lists are under [[#enum-values|enum values]].

{| class="wikitable"
|-
! Field
! Type
! Spec enum
! Notes
{{Field|model=PaymentReconciliation|section=Classification|name=reconciliation_type|type=CharField(100)|notes=<code>PaymentReconciliationTypeOptions</code>}}
{{Field|model=PaymentReconciliation|section=Classification|name=status|type=CharField(100)|notes=<code>PaymentReconciliationStatusOptions</code>}}
{{Field|model=PaymentReconciliation|section=Classification|name=kind|type=CharField(100)|notes=<code>PaymentReconciliationKindOptions</code>}}
{{Field|model=PaymentReconciliation|section=Classification|name=issuer_type|type=CharField(100)|notes=<code>PaymentReconciliationIssuerTypeOptions</code>}}
{{Field|model=PaymentReconciliation|section=Classification|name=outcome|type=CharField(100)|notes=<code>PaymentReconciliationOutcomeOptions</code>}}
{{Field|model=PaymentReconciliation|section=Classification|name=method|type=CharField(100)|notes=<code>PaymentReconciliationPaymentMethodOptions</code>}}
|}

=== Payment details ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=PaymentReconciliation|section=Payment details|name=payment_datetime|type=DateTimeField → datetime | None|notes=When the payment was issued. Optional (default <code>None</code>)}}
{{Field|model=PaymentReconciliation|section=Payment details|name=reference_number|type=CharField(1024) → str | None|notes=Cheque number or payment reference. Optional}}
{{Field|model=PaymentReconciliation|section=Payment details|name=authorization|type=CharField(1024) → str | None|notes=Authorization number. Optional}}
{{Field|model=PaymentReconciliation|section=Payment details|name=disposition|type=TextField → str | None|notes=Message describing the outcome. Optional}}
{{Field|model=PaymentReconciliation|section=Payment details|name=note|type=TextField → str | None|notes=Free-text note. Optional}}
|}

=== Amounts ===

Every amount is a <code>DecimalField(max_digits=20, decimal_places=6)</code>. Six decimal places allow sub-currency precision.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=PaymentReconciliation|section=Amounts|name=tendered_amount|type=Decimal(20, 6)|notes=Required on write. Amount offered by the issuer}}
{{Field|model=PaymentReconciliation|section=Amounts|name=returned_amount|type=Decimal(20, 6)|notes=Required on write. Amount returned to the issuer (e.g. change). Must be strictly less than <code>tendered_amount</code>, or the write is rejected}}
{{Field|model=PaymentReconciliation|section=Amounts|name=amount|type=Decimal(20, 6)|notes=Net payment, computed server-side as <code>tendered_amount - returned_amount</code>. A client-supplied value is always overwritten}}
|}

=== Flags & extensions ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=PaymentReconciliation|section=Flags & extensions|name=is_credit_note|type=BooleanField → bool|notes=Default <code>False</code>. Marks the record as a credit note rather than an inbound payment}}
{{Field|model=PaymentReconciliation|section=Flags & extensions|name=extensions|type=JSONField → dict|notes=Default <code>{}</code>. Open extension bag. On write, each key is validated against the registered handler for resource type <code>payment_reconciliation</code> — unknown keys are currently dropped. On retrieve, rendered through those handlers}}
|}

== Enum values ==

All enums are <code>str, Enum</code> classes in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/payment_reconciliation/spec.py <code>spec.py</code>].

=== <code>PaymentReconciliationTypeOptions</code> (<code>reconciliation_type</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>payment</code>
|-
| <code>adjustment</code>
|-
| <code>advance</code>
|}

=== <code>PaymentReconciliationStatusOptions</code> (<code>status</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>active</code>
|-
| <code>cancelled</code>
|-
| <code>draft</code>
|-
| <code>entered_in_error</code>
|}

=== <code>PaymentReconciliationKindOptions</code> (<code>kind</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>deposit</code>
|-
| <code>periodic_payment</code>
|-
| <code>online</code>
|-
| <code>kiosk</code>
|}

=== <code>PaymentReconciliationIssuerTypeOptions</code> (<code>issuer_type</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>patient</code>
|-
| <code>insurer</code>
|}

=== <code>PaymentReconciliationOutcomeOptions</code> (<code>outcome</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>queued</code>
|-
| <code>complete</code>
|-
| <code>error</code>
|-
| <code>partial</code>
|}

=== <code>PaymentReconciliationPaymentMethodOptions</code> (<code>method</code>) ===

HL7 v2-0570 payment-method codes.

{| class="wikitable"
|-
! Value
! HL7 meaning
|-
| <code>cash</code>
| Cash
|-
| <code>ccca</code>
| Credit card
|-
| <code>cchk</code>
| Cashier's check
|-
| <code>cdac</code>
| Credit/debit account
|-
| <code>chck</code>
| Check
|-
| <code>ddpo</code>
| Direct deposit
|-
| <code>debc</code>
| Debit card
|}

== Resource specs (API schema) ==

Defined in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/payment_reconciliation/spec.py <code>care/emr/resources/payment_reconciliation/spec.py</code>]. All extend <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks). See [[References/Base models & conventions|Base model]].

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BasePaymentReconciliationSpec</code>
| shared base
| Holds <code>id</code>, the six enum fields, <code>disposition</code>, <code>payment_datetime</code>, <code>method</code>, <code>reference_number</code>, <code>authorization</code>, <code>note</code>. <code>__exclude__ = ["target_invoice", "account"]</code> (FKs handled in hooks). <code>___extension_resource_type__ = payment_reconciliation</code>
|-
| <code>PaymentReconciliationWriteSpec</code>
| write · create & update
| Adds <code>target_invoice</code> (UUID, optional), <code>account</code> (UUID, required), <code>tendered_amount</code>, <code>returned_amount</code>, <code>amount</code> (optional), <code>is_credit_note</code> (default <code>False</code>), <code>location</code> (UUID, optional). Mixes in <code>ExtensionValidator</code>
|-
| <code>PaymentReconciliationMinimalReadSpec</code>
| read · list
| Adds <code>amount</code>, <code>tendered_amount</code>, <code>returned_amount</code>, <code>is_credit_note</code>, <code>created_date</code>, <code>modified_date</code>
|-
| <code>PaymentReconciliationReadSpec</code>
| read · detail (nested)
| Extends minimal read; adds <code>account: dict</code> (serialized via <code>AccountReadSpec</code>) and <code>target_invoice: dict | None</code> (serialized via <code>InvoiceReadSpec</code>)
|-
| <code>PaymentReconciliationRetrieveSpec</code>
| read · full retrieve
| Extends read; adds <code>location: dict | None</code> (via <code>FacilityLocationListSpec</code>), <code>extensions: dict</code>, <code>created_by</code> / <code>updated_by</code>. Also injects <code>account.patient</code> via <code>PatientRetrieveSpec</code>
|}

=== Write validation & side effects ===

<code>PaymentReconciliationWriteSpec</code> runs three steps:

* The amount validator (<code>model_validator(mode="after")</code>, <code>check_amount_or_factor</code>) raises <code>"Returned amount cannot be greater than tendered amount"</code> when <code>returned_amount >= tendered_amount</code>, then sets <code>amount = tendered_amount - returned_amount</code>. The spec's <code>amount</code> field is advisory and always recomputed.
* <code>perform_extra_deserialization(is_update, obj)</code> resolves the FK UUIDs to model instances:
** <code>target_invoice</code> (if provided) → <code>Invoice.objects.get(external_id=...)</code>
** <code>account</code> (required) → <code>Account.objects.get(external_id=...)</code>
** <code>location</code> (if provided) → <code>FacilityLocation.objects.get(external_id=...)</code>
* <code>ExtensionValidator.validate_extensions</code> checks <code>extensions</code> against the <code>payment_reconciliation</code> extension registry before save.

=== Read serialization side effects ===

* <code>PaymentReconciliationMinimalReadSpec.perform_extra_serialization</code> maps <code>id</code> ← <code>obj.external_id</code>.
* <code>PaymentReconciliationReadSpec</code> serializes the related <code>account</code> (<code>AccountReadSpec</code>) and, when present, <code>target_invoice</code> (<code>InvoiceReadSpec</code>) into nested objects.
* <code>PaymentReconciliationRetrieveSpec</code> additionally nests the account's <code>patient</code> (<code>PatientRetrieveSpec</code>, scoped to the account's facility), the <code>location</code> (<code>FacilityLocationListSpec</code>), the raw <code>extensions</code>, and audit users (<code>created_by</code> / <code>updated_by</code> via <code>serialize_audit_users</code>).

== Related models ==

<code>PaymentReconciliation</code> is self-contained; its foreign keys reach into the billing and facility domains:

<syntaxhighlight lang="text">facility → FK Facility (PROTECT)
target_invoice → FK Invoice (PROTECT, nullable)
account → FK Account (PROTECT)
location → FK FacilityLocation (PROTECT, nullable)</syntaxhighlight>
Each foreign key uses <code>on_delete=PROTECT</code>, so a payment record blocks deletion of the facility, invoice, account, or location it references.

== Methods & save behaviour ==

<code>PaymentReconciliation</code> defines no custom <code>save()</code>; it inherits <code>EMRBaseModel</code> behaviour (audit fields, <code>external_id</code>, soft delete). Everything below happens in the write spec, not the model:

* <code>amount</code> is derived, not stored as sent. On every create and update the write spec computes <code>amount = tendered_amount - returned_amount</code> and rejects <code>returned_amount >= tendered_amount</code>.
* FK resolution happens in <code>perform_extra_deserialization</code>: <code>external_id</code> UUIDs for <code>account</code>, <code>target_invoice</code>, and <code>location</code> resolve to instances at de-serialization time.
* <code>extensions</code> are validated against the <code>payment_reconciliation</code> registry on write and rendered through registered handlers on retrieve.

== API integration notes ==

* Create and update use <code>PaymentReconciliationWriteSpec</code>; list responses use <code>PaymentReconciliationMinimalReadSpec</code>; detail and retrieve responses use <code>PaymentReconciliationReadSpec</code> / <code>PaymentReconciliationRetrieveSpec</code>.
* <code>account</code> is always required; <code>target_invoice</code> is optional and allocates the payment to one invoice. Pass <code>account</code>, <code>target_invoice</code>, and <code>location</code> as <code>external_id</code> UUIDs.
* The Pydantic schema constrains the six classification fields (<code>reconciliation_type</code>, <code>status</code>, <code>kind</code>, <code>issuer_type</code>, <code>outcome</code>, <code>method</code>) to the enums above and rejects invalid values, even though each column is a plain <code>CharField</code>.
* Send <code>tendered_amount</code> and <code>returned_amount</code> (both required); the server derives <code>amount</code>, so any value you send for it is ignored.
* <code>extensions</code> holds custom key-value data without a schema migration, validated against registered handlers.

{{Related}}

References/Payment Reconciliation - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed