> ## 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.

# Customer Payments

> List, record, view, and manage AR customer payments with invoice applications, receipt PDF generation, and status filters.

Customer Payments lists all accounts-receivable customer payments for the organization with status filters and summary metric cards. Route: `/fa/customer-payments`

## Overview

The route `/fa/customer-payments` redirects to `/fa/receivables?tab=payments` in the router. The `CustomerPaymentsPage` component fetches payments via `useCustomerPayments(organizationId, statusFilter)`. Status filter options: `all`, `unapplied`, `partially_applied`, `fully_applied`. Summary cards show: total received (`payment_amount` sum), total unapplied (`unapplied_amount` sum), and received today. The **New Payment** button navigates to `/fa/customer-payments/new`. The apply-payment dialog (`PaymentApplicationDialog`) can be opened per row.

## Who it's for

Access follows your organization's role and module configuration.

## Before you start

* Customers and invoices must exist before payments can be recorded.
* Have the payment details ready when recording: date, amount, payment method, and optionally check or reference number.

## Steps

<Steps>
  <Step title="Navigate to Customer Payments">
    Go to `/fa/customer-payments` or the Payments tab in the Receivables hub.
  </Step>

  <Step title="Review summary cards">
    Check total received, unapplied balance, and today's received amounts.
  </Step>

  <Step title="Filter by status">
    Select a status filter to narrow to unapplied, partially applied, or fully applied payments.
  </Step>

  <Step title="Apply a payment to an invoice">
    Use the apply action on a payment row to open `PaymentApplicationDialog`.
  </Step>

  <Step title="Open a payment detail">
    Click a payment row to navigate to `/fa/customer-payments/:id`.
  </Step>

  <Step title="Record a new payment">
    Click **New Payment** to navigate to `/fa/customer-payments/new`.
  </Step>
</Steps>

## Key concepts

* **`useCustomerPayments`** — Primary list hook; accepts `organizationId` and optional `{ status }` filter.
* **`unapplied_amount`** — Payment amount not yet applied to invoices.
* **`PaymentApplicationDialog`** — Inline dialog for applying a payment to invoices.
* **`useDeleteCustomerPayment`** — Mutation hook for deleting a payment with confirmation.

## Viewing a customer payment

The detail view at `/fa/customer-payments/:id` displays all information for a single AR customer payment including its application to invoices, with actions to apply, remove applications, generate a receipt PDF, and delete.

The page loads the payment via `useCustomerPayment(id, organizationId)`. Applications are loaded via `useARPaymentApplications`. Breadcrumb shows `payment_number`. Payment metadata includes: `payment_date`, `payment_amount`, `payment_method` (underscores replaced with spaces), `check_number`, and `reference_number`. The applications table (`ARPaymentApplicationWithDetails[]`) shows invoice linkages. Actions: Apply to invoice (`PaymentApplicationDialog`), remove an application (`useRemoveARPaymentApplication`, with confirmation), generate receipt PDF (`usePaymentReceiptPdf`), and delete the payment (`useDeleteCustomerPayment`, with confirmation). The PDF receipt includes vendor/customer name, payment number, date, amount, method, reference, and applied invoice numbers.

Key concepts:

* **`useCustomerPayment`** — Primary data hook; fetches a single payment by `id` and `organizationId`.
* **`useARPaymentApplications`** — Hook fetching invoice application records for this payment.
* **`ARPaymentApplicationWithDetails`** — Type for application rows including linked invoice data.
* **`usePaymentReceiptPdf`** — Hook that generates a receipt PDF from payment and application data.
* **`PaymentApplicationDialog`** — Component for applying the payment to an invoice.

1. Go to `/fa/customer-payments/:id` or click a payment from the Customer Payments list.
2. Review payment number, date, amount, method, and reference information.
3. Review the applications section to see which invoices this payment has been applied to.
4. Click Apply to open `PaymentApplicationDialog` and select an invoice.
5. Click remove on an application row and confirm to call `useRemoveARPaymentApplication`.
6. Click the receipt download button to generate and download a PDF via `usePaymentReceiptPdf` (optional).
7. Click Delete and confirm to call `useDeleteCustomerPayment` (if applicable).

## Creating a customer payment

The New Customer Payment page (`/fa/customer-payments/new`) records a customer payment against the organization's accounts receivable. The page renders `CustomerPaymentForm` inside a "Payment Information" card. The payment number is auto-generated via `useGeneratePaymentNumber`.

On submit, `useCreateCustomerPayment` is called with `organization_id`, `payment_number` (generated), `customer_id`, `payment_date`, `payment_amount`, `payment_method`, optional `check_number`, `reference_number`, `notes`, `created_by`. On success, navigates to `/fa/customer-payments/:id`.

Key concepts:

* **Payment number:** Auto-generated by `useGeneratePaymentNumber`. Not user-entered.

1. Navigate to `/fa/customer-payments/new`.
2. Complete the **Payment Information** form via `CustomerPaymentForm`: customer, payment date, payment amount, payment method; optionally check number, reference number, notes.
3. Submit. On success, you are redirected to the payment detail page.

<Warning>
  SME: The exact fields and payment method options in `CustomerPaymentForm` are not fully observable from the page component alone. Confirm available options with the implementation team.
</Warning>

## Related

<Columns cols={2}>
  <Card title="Finance & Revenue" icon="building-columns" href="/fa/overview">
    Finance & Revenue core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</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/fa.tsx
  * src/cores/fa/pages/CustomerPaymentsPage.tsx
  * src/cores/fa/pages/CustomerPaymentDetailPage.tsx
  * src/cores/fa/pages/CustomerPaymentCreatePage.tsx
  * src/cores/fa/hooks/useCustomerPayments.ts
  * src/cores/fa/hooks/useARPaymentApplications.ts
  * src/cores/fa/hooks/usePaymentReceiptPdf.ts
  * src/cores/fa/components/CustomerPaymentsTable.tsx
  * src/cores/fa/components/PaymentApplicationDialog.tsx
  * src/cores/fa/components/PaymentStatusBadge.tsx
  * src/cores/fa/components/CustomerPaymentForm.tsx
</Accordion>