---
title: "Search & list payments"
method: GET
path: "/payments"
tags: ["Payments API"]
---

# Search & list payments

`GET /payments`

Retrieve a list of your payments. Results are paginated, they will only return up to 100 payments maximum. To access the next page of result, set the \`cursor\` query parameter to the value of \`nextCursor\` in your current result payload. Use \`prevCursor\` to go back to the previous page. \*\*Note:\*\* this endpoint returns a list of summarized payments. Not all payments attributes are present. You can use the query parameters to filter payments. You can separate multiple query parameters with the \`&\` symbol. Query parameters with types of the form "Array of strings" (such as the status parameter) can be specified as a comma-separated list. For example, if you wanted to get both \`FAILED\` and \`CANCELLED\` payments, for customer \`john-123\`, you would use: \`\`\`bash curl --location --request GET 'https://api.primer.io/payments?status=FAILED,CANCELLED&customer\_id=john-123' \\ --header 'X-Api-Key: ' \`\`\` You can alternatively specify a list by repeating the parameter multiple times. \*\*Note:\*\* payments will be available within a minute from being created.

## Query parameters

- `status` PaymentStatus[] — Filter payments by their status.
- `payment_method_type` PaymentMethodTypeEnum[] — Filter payments by their payment method type.
- `processor` string[] — Filter payments by their payment processor.
- `currency_code` string[] — Filter payments by their payment currency. Use the 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars."
- `from_date` string, date-time — Return only payments from this date (inclusive).
- `to_date` string, date-time — Return only payments up to this date (inclusive).
- `order_id` string — Return payments related to this order ID.
- `min_amount` integer — Return payments of this amount minimum (inclusive).
- `max_amount` integer — Return payments of this amount max (inclusive).
- `customer_id` string[] — ID of the customer that has made the payment.
- `merchant_id` string[] — ID of the merchant involved in the payment.
- `customer_email_address` string[] — Email of the customer that has made the payment.
- `last_4_digits` string[] — Last 4 digits of the card used for the payment.
- `paypal_email` string[] — Paypal email address associated with the payment.
- `klarna_email` string[] — Klarna email address associated with the payment.
- `limit` integer — Maximum number of payments to return per page.
- `cursor` string — If results are paginated, pass the `nextCursor` to access next page.

## Headers

- `X-API-VERSION` string, required

## Response `200`

Successful Response

- PaymentListAPIResponse
  - `data` PaymentSummaryAPISchema[], required
    - `id` string, required — The unique payment ID. You can use this ID to retrieve the payment details, or perform downstream operations.
    - `date` string, date-time, required — The date and time at which the payment was created in UTC format.
    - `dateUpdated` string, date-time, required — The date and time of the last payment update in UTC format.
    - `status` 'PENDING' | 'FAILED' | 'AUTHORIZED' | 'SETTLING' | 'PARTIALLY_SETTLED' | 'SETTLED' | 'DECLINED' | 'CANCELLED', required — An enumeration.
    - `orderId` string, required — Your reference for the payment.
    - `processor` PaymentSummaryProcessorAPISchema
      - `name` string, required — The payment processor used for this payment.
      - `processorMerchantId` string — The merchant ID registered at the payment processor used for this payment.
    - `currencyCode` string, required — The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars.
    - `amount` integer, required — The payment amount, in minor units. e.g. $7 would show as `700`.
    - `metadata` object — Additional data to be used throughout the payment lifecycle. A dictionary of key-value pairs where the values can only be strings or integers. e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}`
  - `nextCursor` string
  - `prevCursor` string

## Other responses

- `422` — Error Response

---

[API](https://skmtc.dev/primer/apis/primer-api.md) · [All operations](https://skmtc.dev/primer/apis/primer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primer/primer-api/revisions/a4459530edb7/schema)