> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Practice Management Payments

> Post and track insurance and patient payments, upload ERA files, resolve ERA orphan lines, and view individual payment application detail.

The Payments screen (`/pm/payments`) lists insurance and patient payment records for the current organization and provides workflows for posting manual payments, uploading <Tooltip tip="Electronic Remittance Advice — an electronic file from a payer that explains how a claim was adjudicated and paid.">ERA</Tooltip> files, and resolving unmatched ERA lines in the Orphan Queue.

## Overview

The screen has two tabs: **Payments** and **Orphan Queue**. The Payments tab lists payments ordered by `payment_date` descending. Each card shows the payment number, a status badge (Pending, Posted, Partial, Voided), a type badge (Insurance, Patient, ERA), the payment date, total amount, and unapplied amount when greater than zero. Clicking a card navigates to the payment detail page at `/pm/payments/:paymentId`. The Orphan Queue tab (visible only to users with the `pm.era-orphan.view` permission) shows ERA lines that could not be automatically matched to a claim; a badge on the tab displays the count of pending orphans. Selecting an orphan line opens the `OrphanMatchSheet` side panel.

## Who it's for

Requires the `pm.payments.view` permission. Posting payments and uploading ERA files additionally requires `pm.payments.post` (the `PM_PERMISSIONS.PAYMENTS_POST` constant). Viewing the Orphan Queue additionally requires `pm.era-orphan.view` (`PM_PERMISSIONS.ERA_ORPHAN_VIEW`).

## Before you start

* The `pm.payments.view` permission must be granted for the user's role.
* An organization must be selected; the hook returns an empty array when no org is active.

## Steps

<Steps>
  <Step title="Filter the Payments list">
    On the Payments tab, type in the search box to find payments by payment number. Use the status dropdown (All Statuses, Pending, Posted, Partial, Voided) to narrow the list.
  </Step>

  <Step title="View payment detail">
    Click any payment card to navigate to the detail page at `/pm/payments/:paymentId`.
  </Step>

  <Step title="Post a manual payment">
    Users with `pm.payments.post` will see the "Post Payment" button in the header. Clicking it opens `PaymentPostDialog` to record a new insurance or patient payment.
  </Step>

  <Step title="Upload an ERA file">
    Users with `pm.payments.post` can click "Upload ERA" to open `EraUploadDialog` and import an <Tooltip tip="Electronic Remittance Advice file from a payer describing claim adjudication.">ERA</Tooltip> file. Successfully processed ERA lines are auto-posted where possible; unmatched lines land in the Orphan Queue.
  </Step>

  <Step title="Resolve orphan ERA lines">
    Switch to the Orphan Queue tab (visible when `pm.era-orphan.view` is granted and at least one pending orphan exists). Select an orphan row in `EraOrphanQueueTable` to open `OrphanMatchSheet` and manually match it to a claim.
  </Step>
</Steps>

## Key concepts

<Tooltip tip="An ERA line that the system could not automatically match to an existing claim.">Orphan line</Tooltip>

<AccordionGroup>
  <Accordion title="Empty and error states">
    When no payments match the current filters, the empty state reads "No payments found." When filters are active: "No payments match the current filters." When the fetch fails, an error empty state reads "Unable to load payments. Please try again."
  </Accordion>
</AccordionGroup>

## Viewing a payment

The Payment Details page displays a single payment record and its application lines, with an action to post pending payments at route `/pm/payments/:paymentId` (permission: `pm.payments.view`). Posting requires `pm.payments.post`.

`PaymentDetailPage` loads the payment via `usePaymentDetail` and its application lines via `usePaymentApplicationList`. The dynamic breadcrumb is set to `payment_number`. Status, type, payment method, and application type are rendered using label maps from `src/cores/pm/types/payments.ts`. A **Post Payment** button is shown when `status` is `pending` or `partial`, gated by `PM_PERMISSIONS.PAYMENTS_POST`.

Two tabs are available: one for payment summary details and one for the application lines table.

1. Navigate to **Practice Management → Payments**, select a payment from the list, or go directly to `/pm/payments/:paymentId`.
2. The summary tab shows payment number, type, status, method, and application type using standardized labels.
3. Switch to the applications tab to view how the payment has been applied across claims or accounts.
4. If the payment status is `pending` or `partial`, the **Post Payment** action is available for users with `pm.payments.post` permission.

* **Payment status** — `pending`, `partial`, and other statuses as defined in `PAYMENT_STATUS_LABELS`; only `pending` and `partial` enable the post action.
* **Application lines** — records linking portions of a payment to specific claims or balances.

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/pages/PaymentsListPage.tsx
  * src/cores/pm/hooks/usePaymentList.ts
  * src/cores/pm/types/payments.ts
  * src/cores/pm/pages/PaymentDetailPage.tsx
  * src/cores/pm/hooks/usePaymentDetail.ts
  * src/cores/pm/hooks/usePaymentApplicationList.ts
</Accordion>