Payment

Overview

Payments record money flowing in from customers or out to suppliers. They update accounting records by reducing receivables when customers pay or reducing payables when you pay suppliers. Payments are applied to specific invoices to track which bills have been paid and which amounts remain outstanding.

Customer payments represent money received from customers. When a customer sends payment, you record the amount, payment method (check, credit card, wire transfer, etc.), and reference information like check numbers. The payment is then applied to one or more customer invoices. A single payment might cover multiple invoices, or multiple payments might be needed to fully pay one large invoice. The system tracks these applications so you always know exactly what's been paid.

Supplier payments represent money paid to suppliers for bills. The workflow is similar to customer payments but in reverse - you record the payment details and apply the amount to one or more supplier bills. This reduces your accounts payable balance and provides documentation for cash outflows.

The payment application process is flexible. You can apply a full payment to a single invoice, split one payment across multiple invoices, or make partial payments that don't fully satisfy an invoice. As payments are applied, invoice balances are reduced automatically. This application tracking is essential for accurate accounts receivable and accounts payable management.

Payment records capture important details for reconciliation. The payment date, amount, and reference information (like check numbers or transaction IDs) help match payments to bank deposits or check clearing. Payment method information supports cash management and accounting categorization, as credit card payments might involve processing fees while check payments require different handling.

From a financial perspective, payments create general ledger entries that move money from accounts receivable or accounts payable to cash accounts. Customer payments debit cash and credit accounts receivable. Supplier payments debit accounts payable and credit cash. These entries, combined with the invoice entries, form a complete financial picture of sales, purchases, and cash flows.

GraphQL API

The payment collection provides access to payment data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: paymentViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
15 filter options
24 sortable fields
2 relations to other collections

Query Examples

Basic Query

The payment collection is accessed via the paymentViewConnection query, which returns a Relay-style connection with pagination support.

query {
  paymentViewConnection(first: 10) {
    edges {
      node {
        amount
        creditAccount
        date
        debitAccount
        method
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  paymentViewConnection(first: 50) {
    edges {
      node { paymentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  paymentViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { paymentId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  paymentViewConnection(
    first: 10
    connectionRelationErrorDates: { begin: "2024-01-01", end: "2024-12-31" }
  ) {
    edges {
      node { paymentId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  paymentViewConnection(
    first: 10
    sort: [{ field: "amount", mode: "desc" }]
  ) {
    edges {
      node {
        paymentId
        amount
      }
    }
  }
}

Relations

Query related data (see Relations section for all available relations):

query {
  paymentViewConnection(first: 10) {
    edges {
      node {
        paymentId
        customer {
          name
          partyUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports data aggregation and dimensional analysis through the summary field. You can calculate metrics (like totals, averages, counts) and group them by dimensions (like category, date, status).

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

paymentViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    groupBy {
      # Group by dimensions (see table below)
    }
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 1 metric that can be aggregated:

Metric	Parameters	Description
`count`	None	Count of items in the result set

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

GroupBy Dimensions

Group metrics by these dimensions:

Dimension	Description
`customer`	customer for payment
`supplier`	supplier for payment

All dimensions accept a formatter parameter: "html", "none", "abbreviated", "blank-zero".

Examples

Example 1: Basic Aggregation

Calculate metrics for payment:

query {
  paymentViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        # Add dimensions here
      }
      metrics {
        totalCount: count
      }
    }
  }
}

Fields

This collection has 23 fields:

21 simple fields
2 enum fields (with predefined values)
0 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

`amount`

The total monetary value of the payment. This amount can be distributed across multiple invoices through invoice assignments, and the sum of assigned amounts must not exceed the payment total.

Label: Amount
Sortable: Yes

`creditAccount`

The general ledger account to be credited for this payment transaction. This account is part of the double-entry accounting system and represents where funds are coming from in the financial records.

Label: Credit account
Sortable: Yes

`date`

The date when the payment was made or received. This date is used for financial reporting and determines when the transaction is recorded in the accounting period.

Label: Date
Sortable: Yes

`debitAccount`

The general ledger account to be debited for this payment transaction. This account is part of the double-entry accounting system and represents where funds are being deposited in the financial records.

Label: Debit account
Sortable: Yes

`hasAttachment`

Indicates whether the payment has an associated file attachment, such as a receipt or supporting documentation. Displays an attachment icon when files are present.

Label: Has attachment
Type: ##iconWithTooltip
Sortable: No

`method`

The method used to make the payment, such as Cash, Credit, Check, or Gift card. Available payment methods are configured per payment type and can be customized for sales and purchase payments.

Label: Method
Sortable: Yes

`paymentId`

The unique identifier for the payment record. This ID is used to reference and link to the payment detail page and track the payment throughout the system.

Label: Payment ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  payment(paymentUrl: "example-url") {
    paymentId    # Uses default formatter: html
    paymentIdRaw: paymentId(formatter: "none")  # Get raw value
  }
}

`paymentUrl`

The unique identifier for the payment record. This URL is automatically generated by the server and is used to retrieve payment data and establish relationships with other entities like invoices and orders.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: Payment Url
Sortable: Yes

`privateNotes`

Internal notes that are only visible to staff members and not shared with customers or suppliers. These notes support HTML escaping and newline formatting for detailed record-keeping.

Label: Internal notes
Sortable: Yes
Default Formatter: html

Example Query:

{
  payment(paymentUrl: "example-url") {
    privateNotes    # Uses default formatter: html
    privateNotesRaw: privateNotes(formatter: "none")  # Get raw value
  }
}

`publicNotes`

Public notes that can be shared with customers or suppliers. These notes support HTML escaping and newline formatting for clear communication about the payment.

Label: Public notes
Sortable: Yes
Default Formatter: html

Example Query:

{
  payment(paymentUrl: "example-url") {
    publicNotes    # Uses default formatter: html
    publicNotesRaw: publicNotes(formatter: "none")  # Get raw value
  }
}

`recordCreated`

The date and time when the payment record was originally created in the system. This field is automatically set and cannot be imported or modified.

Label: Record created
Sortable: Yes

`recordLastUpdated`

The date and time when the payment record was last modified. This field is automatically updated whenever changes are made and cannot be imported or manually set.

Label: Record last updated
Sortable: Yes

`referenceNumber`

An optional reference number for the payment, typically used to track external payment identifiers like check numbers, wire transfer references, or third-party payment system transaction IDs.

Label: Reference number
Sortable: Yes

`statusExtended`

A human-readable formatted version of the payment status that provides additional context based on the associated invoice and payment state. This is a read-only computed field.

Label: Status extended
Sortable: Yes

`syncStatus`

The synchronization status of the payment with external accounting systems. This field shows whether the payment has been synced, is not synced, is partially synced, is excluded from syncing, has errors, or is invalid based on connection relationship data.

Label: Sync status
Sortable: Yes

`syncStatusConnection`

Displays the connection IDs for all sync operations related to this payment. This field shows which external accounting system connections are involved in syncing this payment, formatted as a comma-separated list of connection labels.

Label: Sync status connection ID
Sortable: Yes

`syncStatusFrom`

The synchronization status for payments being imported from external accounting systems into Finale. This field filters sync status to show only inbound synchronization operations where data flows from external systems to Finale.

Label: Synced from
Sortable: Yes

`syncStatusFromConnection`

Displays the connection IDs for inbound sync operations where payments are imported from external accounting systems. This field shows which connections are used to bring payment data into Finale.

Label: Synced from connection ID
Sortable: Yes

`syncStatusTo`

The synchronization status for payments being exported from Finale to external accounting systems. This field filters sync status to show only outbound synchronization operations where data flows from Finale to external systems.

Label: Synced to
Sortable: Yes

`syncStatusToConnection`

Displays the connection IDs for outbound sync operations where payments are exported to external accounting systems. This field shows which connections are used to send payment data from Finale to external systems.

Label: Synced to connection ID
Sortable: Yes

`title`

A computed display title for the payment that varies based on the payment type. For purchase payments, it displays as a bill payment title, while for sales payments, it displays as an invoice payment title, providing context-appropriate labeling in the user interface.

Label: Title
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

`status`

The current status of the payment. Valid statuses are PAYMENT_DRAFT (not yet finalized), PAYMENT_COMPLETED (processed and recorded), or PAYMENT_CANCELLED (voided or reversed).

Label: Status
Sortable: Yes

Possible Values:

PAYMENT_DRAFT - Draft
PAYMENT_COMPLETED - Posted
PAYMENT_CANCELLED - Canceled

`type`

Label: Type
Sortable: Yes

Possible Values:

PURCHASE_PAYMENT - Purchase payment
SALES_PAYMENT - Sales payment

Relations

customer

Related Collection: party
Label: Customer

TODO: Add relation description

connectionRelation

Related Collection: connectionRelation
Label: Integration

TODO: Add relation description

Filters

connectionRelationErrorDates

Label: Latest error date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    connectionRelationErrorDates: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        paymentId
        connectionRelationErrorDates
      }
    }
  }
}

connectionRelationSyncStatuses

Label: Sync status
Type: List|String
Enabled: Yes
Options:
- Excluded from syncing (##crStatusSkipped)
- Has error (##crStatusError)
- Not synced (##crStatusNotPushed)
- Partially synced (##crStatusPartiallySynced)
- Synced (##crStatusPushed)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoicePayment") {
    dataSets(name: "payment") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    connectionRelationSyncStatuses: ["##crStatusNotPushed", "##crStatusPushed"]
  ) {
    edges {
      node {
        paymentId
        connectionRelationSyncStatuses
      }
    }
  }
}

creditAccount

Label: Credit account
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  paymentViewConnection(
    first: 10
    creditAccount: "Cash"
  ) {
    edges {
      node {
        paymentId
        creditAccount
      }
    }
  }
}

customer

Label: Customer
Type: List|PartyUrlCustomerString
Enabled: Yes

Filter Type: Reference to party collection

Note: Filters to customers only

This filter accepts values from the partyViewConnection query. To get available values:

query {
  partyViewConnection(
    first: 100
    role: ["CUSTOMER"]
    status: "PARTY_ENABLED"
  ) {
    edges {
      node {
        partyUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    customer: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        paymentId
        party {
          name
        }
      }
    }
  }
}

date

Label: Date
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    date: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        paymentId
        date
      }
    }
  }
}

debitAccount

Label: Debit account
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  paymentViewConnection(
    first: 10
    debitAccount: "Accounts Receivable"
  ) {
    edges {
      node {
        paymentId
        debitAccount
      }
    }
  }
}

method

Label: Method
Type: List|String
Enabled: Yes

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  paymentViewConnection(
    first: 10
    method: "Credit Card"
  ) {
    edges {
      node {
        paymentId
        method
      }
    }
  }
}

paymentUrl

Label: Payment
Type: List|PaymentUrlString
Enabled: Yes

Filter Type: Reference to payment collection

This filter accepts values from the paymentViewConnection query. To get available values:

query {
  paymentViewConnection(
    first: 100
  ) {
    edges {
      node {
        paymentUrl    # Use this value in the filter
        paymentId
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    paymentUrl: ["PAYMENT_URL_VALUE"]
  ) {
    edges {
      node {
        paymentId
        payment {
          paymentId
        }
      }
    }
  }
}

recordCreated

Label: Created
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    recordCreated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        paymentId
        recordCreated
      }
    }
  }
}

recordLastUpdated

Label: Last updated
Type: dateRangeInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    recordLastUpdated: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        paymentId
        recordLastUpdated
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  paymentViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        paymentId
      }
    }
  }
}

searchCustom

Label: Not specified
Type: searchCustomFilter
Enabled: Yes

Filter Type: Advanced search with result expansion

See the Advanced Search guide for complete documentation on how this filter works.

Collection-Specific Examples:

Example 1: Basic search:

query {
  paymentViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        paymentId
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS custom fields
query {
  paymentViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["customField1", "customField2"]
    }
  ) {
    edges {
      node {
        paymentId
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each match, also return the related record
query {
  paymentViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        paymentId
      }
    }
  }
}

Example 4: Combine include and extend:

# Search in defaults + additional fields, then expand to related records
query {
  paymentViewConnection(
    first: 10
    searchCustom: {
      terms: "acme corp"
      include: ["customField1"]
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        paymentId
      }
    }
  }
}

status

Label: Status
Type: List|String
Enabled: Yes
Options:
- Canceled (PAYMENT_CANCELLED)
- Draft (PAYMENT_DRAFT)
- Posted (PAYMENT_COMPLETED)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoicePayment") {
    dataSets(name: "payment") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    status: ["PAYMENT_DRAFT", "PAYMENT_COMPLETED"]
  ) {
    edges {
      node {
        paymentId
        status
      }
    }
  }
}

supplier

Label: Supplier
Type: List|PartyUrlSupplierString
Enabled: Yes

Filter Type: Reference to party collection

Note: Filters to suppliers only

This filter accepts values from the partyViewConnection query. To get available values:

query {
  partyViewConnection(
    first: 100
    role: ["SUPPLIER"]
    status: "PARTY_ENABLED"
  ) {
    edges {
      node {
        partyUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    supplier: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        paymentId
        party {
          name
        }
      }
    }
  }
}

type

Label: Type
Type: List|String
Enabled: Yes
Options:
- Purchase payment (PURCHASE_PAYMENT)
- Sales payment (SALES_PAYMENT)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiInvoicePayment") {
    dataSets(name: "payment") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  paymentViewConnection(
    first: 10
    type: ["PURCHASE_PAYMENT", "SALES_PAYMENT"]
  ) {
    edges {
      node {
        paymentId
        type
      }
    }
  }
}