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

# List payments

`GET /api/v1/payments`

## Request

- Base URL: `https://demo.invoiceninja.com`
- URL: `https://demo.invoiceninja.com/api/v1/payments`
- Auth: none declared. Required headers: `X-API-TOKEN`, `X-Requested-With`
- TypeScript: <https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/docs/api/v1/payments/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists payments, search and filters allow fine grained lists to be generated.

        Query parameters can be added to performed more fine grained filtering of the payments, these are handled by the PaymentFilters class which defines the methods available

## Query parameters

- `include` string
- `index` string
- `per_page` integer
- `page` integer
- `sort` string[]
- `status` string
- `client_id` string
- `created_at` integer
- `updated_at` integer
- `is_deleted` boolean
- `filter_deleted_clients` string
- `vendor_id` string
- `filter` string
- `number` string

## Headers

- `X-API-TOKEN` string, required
- `X-Requested-With` string, required

## Response `200`

A list of payments

- object
  - `data` Payment[]
    - `id` string: The payment hashed id
    - `client_id` string: The client hashed id
    - `invitation_id` string: The invitation hashed id
    - `client_contact_id` string: The client contact hashed id
    - `user_id` string: The user hashed id
    - `type_id` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '27' | '28' | '29' | '30' | '31' | '32' | '33': The payment type used to complete this payment
    - `date` string: The Payment date
    - `transaction_reference` string: The transaction reference as defined by the payment gateway
    - `assigned_user_id` string: The assigned user hashed id
    - `private_notes` string: The private notes of the payment
    - `is_manual` boolean: Flags whether the payment was made manually or processed via a gateway
    - `is_deleted` boolean: Defines if the payment has been deleted
    - `amount` number: The amount of this payment
    - `refunded` number: The refunded amount of this payment
    - `updated_at` number: Timestamp
    - `archived_at` number: Timestamp
    - `company_gateway_id` string: The company gateway id
    - `paymentables` Paymentable
      - `id` string: The paymentable hashed id
      - `invoice_id` string: The invoice hashed id
      - `credit_id` string: The credit hashed id
      - `refunded` number, float: The amount that has been refunded for this payment
      - `amount` number, float: The amount that has been applied to the payment
      - `updated_at` number: Timestamp
      - `created_at` number: Timestamp
    - `invoices` InvoicePaymentable[]
      - `invoice_id` string: ______
      - `amount` string: ______
    - `credits` CreditPaymentable[]
      - `credit_id` string: The credit hashed id
      - `amount` string: The credit amount
    - `number` string: The payment number - is a unique alpha numeric number per payment per company
    - `category_id` string: The unique identifier of the payment category
    - `custom_value1` string: Custom field for storing additional information
    - `custom_value2` string: Custom field for storing additional information
    - `custom_value3` string: Custom field for storing additional information
    - `custom_value4` string: Custom field for storing additional information
    - `exchange_currency_id` string: The unique identifier of the exchange currency
    - `exchange_rate` number, float: The exchange rate used for currency conversion
    - `idempotency_key` string: Unique key to ensure idempotent payment processing
  - `meta` Meta
    - `pagination` Pagination
      - `total` integer: The total number of items
      - `count` integer: The number of items per page
      - `per_page` integer: The number of items per page
      - `current_page` integer: The current page number
      - `total_pages` integer: The total number of pages
      - `links` object: The pagination links

## Other responses

- `401`: Authentication error
- `403`: Authorization error
- `422`: Validation error
- `429`: Rate Limit Exceeded
- `5XX`: Server error
- `default`: Unexpected Error

## Changes

- **2026-05-06** `89876e7e51d6`: 1 info
  - for the `query` request parameter `sort`, the type was generalized from `string` to `array`
- **2026-04-20** `69a36036d334`: 2 info
  - the response optional property `data/items/id` became read-only for the status `200`
  - the response optional property `data/items/paymentables/id` became read-only for the status `200`
- **2025-11-22** `00ad5cc89fad`: 8 info
  - added the optional property `data/items/category_id` to the response with the `200` status
  - added the optional property `data/items/custom_value1` to the response with the `200` status
  - added the optional property `data/items/custom_value2` to the response with the `200` status
  - added the optional property `data/items/custom_value3` to the response with the `200` status
  - …4 more
- **2025-10-10** `f36c4f94ae7b`: 3 info
  - added the new optional `query` request parameter `index`
  - added the new optional `query` request parameter `page`
  - added the new optional `query` request parameter `per_page`
- …earlier changes not shown

[Operation history](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/changes/api/v1/payments/get.md)

---

[API](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference.md) - [All operations](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/revisions/bcda1f823746?raw)