---
title: "List Payments"
method: GET
path: "/payments"
tags: ["Payments"]
---

# List Payments

`GET /payments`

## Request

- Base URL: `https://api.upflow.io/v1`
- URL: `https://api.upflow.io/v1/payments`
- Auth: API key in header `X-Api-Key` and API key in header `X-Api-Secret`

List payments with optional filtering.

## Query parameters

- `offset` integer
- `page` integer
- `limit` integer
- `sortBy` 'updatedAt' | 'validatedAt' | 'createdAt'
- `sortOrder` 'DESC' | 'ASC'
- `updatedAt` RangeQueryUpdateSpecs: Only return entities that were updated during the given date range. (ISO 8601 format)
  - `updatedAt.gt` string, date-time: Minimum value to filter by (exclusive)
  - `updatedAt.gte` string, date-time: Minimum value to filter by (inclusive)
  - `updatedAt.lt` string, date-time: Maximum value to filter by (exclusive)
  - `updatedAt.lte` string, date-time: Maximum value to filter by (inclusive)
- `validatedAt` RangeQueryValidationSpecs: Only return entities that were validated during the given date range. (ISO 8601 format)
  - `validatedAt.gt` string, date-time: Minimum value to filter by (exclusive)
  - `validatedAt.gte` string, date-time: Minimum value to filter by (inclusive)
  - `validatedAt.lt` string, date-time: Maximum value to filter by (exclusive)
  - `validatedAt.lte` string, date-time: Maximum value to filter by (inclusive)
- `amountLinked` integer
- `amountLinked.gt` integer
- `amountLinked.gte` integer
- `amountLinked.lt` integer
- `amountLinked.lte` integer
- `amount` integer
- `amount.gt` integer
- `amount.gte` integer
- `amount.lt` integer
- `amount.lte` integer
- `customer.id` string
- `customer.externalId` string
- `modifiedAt` RangeQueryModificationSpecs: Only return entities that were modified during the given date range. (ISO 8601 format)
  - `modifiedAt.gt` string, date-time: Minimum value to filter by (exclusive)
  - `modifiedAt.gte` string, date-time: Minimum value to filter by (inclusive)
  - `modifiedAt.lt` string, date-time: Maximum value to filter by (exclusive)
  - `modifiedAt.lte` string, date-time: Maximum value to filter by (inclusive)

## Response `200`

Paginated list of payments.

- PaymentsListResponse
  - `offset` integer: 0-based index of the first item returned. Returned when using offset-based pagination or by default.
  - `page` integer: Page number (1-based). Returned when using page-based pagination.
  - `limit` integer, required: Maximum number of items returned.
  - `total` integer, required: Total items in the set.
  - `items` Payment[], required
    - `refNumber` string, required: Payment reference number.
    - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
    - `amount` integer, required: Payment amount (in cents).
    - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
    - `validatedAt` string, date-time, required: The date when the payment is validated (ISO 8601 format).
    - `externalId` string: Payment external identifier.
    - `customFields` CustomFieldValueAttribs[]: List of payment's custom fields values.
      - `id` string, uuid, nullable: The Custom Field ID.
      - `externalId` string, nullable: Custom field external identifier.
      - `value` union: The value of the custom field. Can be a primitive (string, integer, boolean), a single object for SELECT types, an array of objects for MULTI_SELECT types.
        - integer: Integer value.
        - string: String value (could also be date-time or date).
        - boolean: Boolean value.
        - CustomFieldValueOption
          - `externalId` string, nullable: External identifier for the option.
          - `label` string, required: Display label for the option.
        - CustomFieldValueOption[]: Value for MULTI_SELECT type.
          - `externalId` string, nullable: External identifier for the option.
          - `label` string, required: Display label for the option.
    - `id` string, uuid, required: The Payment ID.
    - `type` 'ACCOUNT' | 'MANUAL' | 'PARSED_INVOICE' | 'API' | 'BATCH_IMPORT' | 'NATIVE_INTEGRATION': Source or method by which the payment was created.
    - `amountLinked` integer, required: Amount allocated to invoices (in cents).
    - `modifiedAt` string, date-time, required: The date when the payment was last updated (ISO 8601 format).
    - `linkedInvoices` InvoiceAllocation[], required: List of linked invoices with the allocated amount.
      - `linkedAmount` integer, required: Payment share allocated to the invoice (in cents).
      - `invoice` InvoiceLite, required: Minimal invoice information.
        - `id` string, uuid, required: The Invoice ID.
        - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
        - `status` 'DUE' | 'OVERDUE' | 'PAID' | 'WRITTEN_OFF' | 'DISPUTED', required: Status of the invoice.
        - `amountOutstanding` integer, required: Outstanding amount (in cents).
        - `customId` string: Invoice custom identifier.
        - `grossAmount` integer, required: Amount including taxes (in cents).
        - `netAmount` integer, required: Amount net of taxes (in cents).
        - `name` string: The invoice name or description.
        - `issuedAt` string, date-time, required: The date at which the invoice was issued (ISO 8601 format).
        - `dueDate` string, date-time, required: The date when the invoice is due (ISO 8601 format).
        - `paidDate` string, date-time, nullable: The date when the invoice was paid (ISO 8601 format).
        - `externalId` string: Invoice external identifier.
    - `customer` CustomerLite: Minimal customer information.
      - `id` string, uuid, required: The Customer ID.
      - `externalId` string: An external ID that uniquely references the customer.
      - `companyName` string, required: Customer name.
      - `accountingRef` string: (Deprecated) Customer accounting reference (used in accounting tool). Use a custom field instead.
    - `createdAt` string, date-time: The date at which the payment was created (ISO 8601 format).
    - `updatedAt` string, date-time: The date at which the payment was last updated (ISO 8601 format).

---

[API](https://skmtc.dev/upflow/apis/upflow-api.md) - [All operations](https://skmtc.dev/upflow/apis/upflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upflow/apis/upflow-api/revisions/898a98ca0587?raw)