---
title: "Query payments"
method: POST
path: "/v2/payments/query"
tags: ["Payments"]
---

# Query payments

`POST /v2/payments/query`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/payments/query`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payments:read`
  - OAuth 2
    - Client credentials
    - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payments:read_write`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/payments/query/post.ts> (a function with typed inputs; its response is checked against the schema)

Query payments filtering, and sorting and paginating results.

See [Query resources](#tag/Queries/operation/query_resources) for more examples and details
about other resources, pagination and everything related to operate the Getpaid solution.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- QueryPaymentsRequest
  - `type` 'payments', required: The type of the Getpaid solution resources to query. Some query endpoints infer the resource type from the request path. In those cases, if this field is set, it must match the resource targeted by the request URL.
  - `first` integer: Pagination. The number of elements that will be retrieved.
  - `after` string: Pagination. The `cursor` from next page will be retrieved.
  - `filters` object: Filtering payments.
    - `id` string, id: The unique identifier of the payment.
    - `reference` string: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `seller_legal_name` string: The legal name of the account.
    - `statuses` PaymentStatus[]: The list of payment statuses to filter by.
  - `sorts` object[]: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
    - `field` 'created_at' | 'amount' | 'seller_legal_name', required: The field to sort by. Each field available can only be used once in the list.
    - `direction` 'ascending' | 'descending', required: The sort direction

## Response `200`

OK

- QueryPaymentsResponse
  - `type` 'payments', required
  - `cursor` string: The cursor to the last item. If non-empty, can be used to fetch the next page. If not set, there is no more elements.
  - `data` object[], required: The list of queried elements.
    - `id` string, id, required: The unique identifier of the payment.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `status` 'initiated' | 'action_required' | 'submitted' | 'authorized' | 'captured' | 'declined' | 'failed' | 'partially_refunded' | 'refunded', required: The status of the payment. See the [list, transitions, and description of each status](/payments/lifecycle) for more details.
    - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
    - `currency` string, currency, required: The processing currency code according to the [ISO-4217 standard](https://en.wikipedia.org/wiki/ISO_4217)
    - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `method` union, required: The payment method used.
      - BasePaymentMethodHint
        - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
        - `display_hint` string, required: A hint of the payment method used.
      - CardPaymentMethodHint
        - `type` 'card' | 'sepa_direct_debit', required: The type of payment method.
        - `scheme` 'visa' | 'mastercard', required: The card scheme.
        - `display_hint` string, required: A hint of the payment method used.
    - `seller` SellerRef, required: A reference to the seller account.
      - `id` string, id, required: The unique identifier of the account.
      - `legal_name` string, required: The legal name of the account.
    - `parties` PartyRef[], required: The list of parties involved in the transaction.
      - `id` string, id, required: The unique identifier of the account.
      - `type` 'platform' | 'other', required: The type of party.
      - `legal_name` string, required: The legal name of the account.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

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