Billing

Payment Reconciliation

A PaymentReconciliation is a single payment recorded against an Account, and optionally allocated to one Invoice. It captures how much was paid, by what method, when, and by whom — mirroring the FHIR PaymentReconciliation resource. Reach for it…

3.1 · versioned documentation · 7 min read

A PaymentReconciliation is a single payment recorded against an Account, and optionally allocated to one Invoice. It captures how much was paid, by what method, when, and by whom — mirroring the FHIR PaymentReconciliation resource. Reach for it whenever you post a payment, refund, credit note, or adjustment to a patient or insurer account.

Source:

• Model: care/emr/models/payment_reconciliation.py
• Resource spec: care/emr/resources/payment_reconciliation/spec.py

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

Models

The model extends EMRBaseModel, the shared MANSOQ EMR base supplying external_id, audit fields, and soft-delete semantics — see Base model.

PaymentReconciliation fields

Relationships

Classification

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

Payment details

Amounts

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

Flags & extensions

Enum values

All enums are str, Enum classes in spec.py.

PaymentReconciliationTypeOptions (reconciliation_type)

PaymentReconciliationStatusOptions (status)

PaymentReconciliationKindOptions (kind)

PaymentReconciliationIssuerTypeOptions (issuer_type)

PaymentReconciliationOutcomeOptions (outcome)

PaymentReconciliationPaymentMethodOptions (method)

HL7 v2-0570 payment-method codes.

Resource specs (API schema)

Defined in care/emr/resources/payment_reconciliation/spec.py. All extend EMRResource (serialize / de_serialize, with perform_extra_serialization / perform_extra_deserialization hooks). See Base model.

Write validation & side effects

PaymentReconciliationWriteSpec runs three steps:

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

Read serialization side effects

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

Related models

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

facility       → FK Facility (PROTECT)
target_invoice → FK Invoice (PROTECT, nullable)
account        → FK Account (PROTECT)
location       → FK FacilityLocation (PROTECT, nullable)

Each foreign key uses on_delete=PROTECT, so a payment record blocks deletion of the facility, invoice, account, or location it references.

Methods & save behaviour

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

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

API integration notes

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

Related

• Reference: Account
• Reference: Invoice
• Reference: Charge item
• Reference: Base model
• Source (model): payment_reconciliation.py on GitHub
• Source (spec): payment_reconciliation/spec.py on GitHub

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/billing/payment-reconciliation.mdx:1 · f6e9f05f