> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & list payments

> <p/>

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: <YOUR_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.




## OpenAPI

````yaml https://api.schemas.primer.io/api-reference/v2.4/openapi.yaml get /payments
openapi: 3.0.2
info:
  x-logo:
    url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
  title: Primer API
  version: '2.4'
  description: >-
    This API enforces a timeout of 90 seconds for all requests. A 504 response
    indicates a timeout has occurred.
servers:
  - url: https://api.sandbox.primer.io
  - url: https://api.primer.io
security:
  - ApiKeyAuth: []
tags:
  - name: Client Session API
  - name: Payments API
  - name: Payment Methods API
paths:
  /payments:
    get:
      tags:
        - Payments API
      summary: Search & list payments
      description: >
        <p/>


        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: <YOUR_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.
      operationId: list_payments_payments_get
      parameters:
        - description: Filter payments by their status.
          required: false
          schema:
            title: Payment status
            type: array
            items:
              $ref: '#/components/schemas/PaymentStatus'
            description: Filter payments by their status.
          name: status
          in: query
        - description: Filter payments by their payment method type.
          required: false
          schema:
            title: Payment method type
            type: array
            items:
              $ref: '#/components/schemas/PaymentMethodTypeEnum'
            description: Filter payments by their payment method type.
          name: payment_method_type
          in: query
        - description: Filter payments by their payment processor.
          required: false
          schema:
            title: Payment processor
            type: array
            items:
              type: string
            description: Filter payments by their payment processor.
          name: processor
          in: query
        - description: |
            Filter payments by their payment currency.
            e.g. use `USD` for US dollars.
          required: false
          schema:
            title: Payment currency
            type: array
            items:
              type: string
            description: >
              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."
          name: currency_code
          in: query
        - description: Return only payments from this date (inclusive).
          required: false
          schema:
            title: Payment date
            type: string
            description: Return only payments from this date (inclusive).
            format: date-time
          name: from_date
          in: query
        - description: Return only payments up to this date (inclusive).
          required: false
          schema:
            title: Payment date
            type: string
            description: Return only payments up to this date (inclusive).
            format: date-time
          name: to_date
          in: query
        - description: Return payments related to this order ID.
          required: false
          schema:
            title: Payment order ID
            type: string
            description: Return payments related to this order ID.
          name: order_id
          in: query
        - description: Return payments of this amount minimum (inclusive).
          required: false
          schema:
            title: Payment amount
            type: integer
            format: int64
            description: Return payments of this amount minimum (inclusive).
          name: min_amount
          in: query
        - description: Return payments of this amount max (inclusive).
          required: false
          schema:
            title: Payment amount
            type: integer
            format: int64
            description: Return payments of this amount max (inclusive).
          name: max_amount
          in: query
        - description: ID of the customer that has made the payment.
          required: false
          schema:
            title: Customer ID
            type: array
            items:
              type: string
            description: ID of the customer that has made the payment.
          name: customer_id
          in: query
        - description: ID of the merchant involved in the payment.
          required: false
          schema:
            title: Merchant ID
            type: array
            items:
              type: string
            description: ID of the merchant involved in the payment.
          name: merchant_id
          in: query
        - description: Email of the customer that has made the payment.
          required: false
          schema:
            title: Customer email address
            type: array
            items:
              type: string
            description: Email of the customer that has made the payment.
          name: customer_email_address
          in: query
        - description: Last 4 digits of the card used for the payment.
          required: false
          schema:
            title: Last 4 digits
            type: array
            items:
              type: string
            description: Last 4 digits of the card used for the payment.
          name: last_4_digits
          in: query
        - description: Paypal email address associated with the payment.
          required: false
          schema:
            title: Paypal email
            type: array
            items:
              type: string
            description: Paypal email address associated with the payment.
          name: paypal_email
          in: query
        - description: Klarna email address associated with the payment.
          required: false
          schema:
            title: Klarna email
            type: array
            items:
              type: string
            description: Klarna email address associated with the payment.
          name: klarna_email
          in: query
        - description: Maximum number of payments to return per page.
          required: false
          schema:
            title: Limit result set
            maximum: 100
            minimum: 1
            type: integer
            format: int64
            description: Maximum number of payments to return per page.
            default: 100
          name: limit
          in: query
        - description: If results are paginated, pass the `nextCursor` to access next page.
          required: false
          schema:
            title: Page cursor
            type: string
            description: >-
              If results are paginated, pass the `nextCursor` to access next
              page.
          name: cursor
          in: query
        - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListAPIResponse'
        '422':
          description: Error Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422ErrorResponse'
              example:
                error:
                  errorId: RequestValidationError
                  description: Invalid type for `currencyCode`
                  recoverySuggestion: The currency code must be a valid value
                  diagnosticsId: '1234567898'
components:
  schemas:
    PaymentStatus:
      title: PaymentStatus
      enum:
        - PENDING
        - FAILED
        - AUTHORIZED
        - SETTLING
        - PARTIALLY_SETTLED
        - SETTLED
        - DECLINED
        - CANCELLED
      type: string
      description: An enumeration.
    PaymentMethodTypeEnum:
      title: PaymentMethodTypeEnum
      enum:
        - PAYMENT_CARD
        - GOOGLE_PAY
        - APPLE_PAY
        - PAYPAL
        - BANK_ACCOUNT
        - KLARNA
        - APAYA
        - OPENNODE
        - HOOLAH
        - ATOME
        - COINBASE
        - NETS
        - TWOC2P
        - CLEARPAY
        - SHOPEEPAY
        - TRIPLE_A
        - AFTERPAY
        - NOL_PAY
        - PAY_NL_IDEAL
        - PAY_NL_BANCONTACT
        - PAY_NL_DIRECT_DEBIT
        - PAY_NL_SOFORT_BANKING
        - PAY_NL_PAYPAL
        - PAY_NL_PAYCONIQ
        - PAY_NL_GIROPAY
        - PAY_NL_P24
        - PAY_NL_EPS
        - PAY_NL_KAARTDIRECT
        - ADYEN_SOFORT
        - ADYEN_TWINT
        - ADYEN_GIROPAY
        - ADYEN_TRUSTLY
        - ADYEN_ALIPAY
        - ADYEN_MOBILEPAY
        - ADYEN_MULTIBANCO
        - ADYEN_VIPPS
        - ADYEN_DOTPAY
        - ADYEN_IDEAL
        - ADYEN_BLIK
        - ADYEN_PAYTRAIL
        - ADYEN_INTERAC
        - ADYEN_PAYSHOP
        - ADYEN_MBWAY
        - ADYEN_AFFIRM
        - ADYEN_KLARNA
        - ADYEN_BANCONTACT_PAYCONIQ
        - ADYEN_EPS
        - ADYEN_BANCONTACT_CARD
        - ADYEN_SWISH
        - MOLLIE_IDEAL
        - MOLLIE_BANCONTACT
        - MOLLIE_P24
        - MOLLIE_GIROPAY
        - MOLLIE_EPS
        - MOLLIE_GIFTCARD
        - MOLLIE_SOFORT
        - NETAXEPT_PAYTRAIL
        - BUCKAROO_IDEAL
        - BUCKAROO_BANCONTACT
        - BUCKAROO_SOFORT
        - BUCKAROO_GIROPAY
        - BUCKAROO_EPS
        - RAPYD_GCASH
        - RAPYD_PROMPTPAY
        - RAPYD_GRABPAY
        - RAPYD_POLI
        - RAPYD_FAST
        - XFERS_PAYNOW
        - STRIPE_GIROPAY
        - STRIPE_IDEAL
        - ALIPAY_CN
        - CHAI_KAKAOPAY
        - CHAI_NAVER
        - CHAI_TOSS
        - XENDIT_DANA
        - XENDIT_OVO
        - XENDIT_SHOPEEPAY
        - XENDIT_RETAIL_OUTLETS
        - OMISE_PROMPTPAY
        - OMISE_TRUEMONEY
        - EBANX_PAGOFACIL
        - PACYPAY_WECHAT
        - PACYPAY_ALIPAY
        - PACYPAY_ALIPAY_PLUS
        - WORLDPAY_IDEAL
        - IPAY88_CARD
        - INGENICO_PAYPAL
        - VOLT_PIX
        - VOLT_BANK_TRANSFER
        - BRAINTREE_VENMO
        - THUNES_SPIRIT_OF_CADEAU
        - THUNES_ILLICADO
        - THUNES_CARTE_CADEAU_CONFORAMA
        - THUNES_CHEQUE_FIDELITE_CONFORAMA
        - SIPS_CPAY
        - SIPS_CPAYCONFORAMA
        - MONEXT_CETELEM
        - MONEXT_CPAY
      type: string
      description: >-
        Payment method type, where `OFF_SESSION_PAYMENT` is used for APM
        (Alternative Payment Method) payments and `PAYMENT_CARD` for traditional
        debit or credit cards. Please note that this list is different from one
        indicated on [available payment
        methods](/docs/connections/payment-methods/available-payment-methods)
        page and values of this field will be changed in the future versions of
        the API.
    PaymentListAPIResponse:
      title: PaymentListAPIResponse
      required:
        - data
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/PaymentSummaryAPISchema'
        nextCursor:
          title: Nextcursor
          type: string
        prevCursor:
          title: Prevcursor
          type: string
    422ErrorResponse:
      title: 422ErrorResponse
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    PaymentSummaryAPISchema:
      title: PaymentSummaryAPISchema
      required:
        - id
        - date
        - dateUpdated
        - status
        - orderId
        - currencyCode
        - amount
      type: object
      properties:
        id:
          title: Payment identifier
          type: string
          description: >
            The unique payment ID.


            You can use this ID to retrieve the payment details, or perform
            downstream

            operations.
        date:
          title: Payment date
          type: string
          description: The date and time at which the payment was created in UTC format.
          format: date-time
        dateUpdated:
          title: Payment updated date
          type: string
          description: The date and time of the last payment update in UTC format.
          format: date-time
        status:
          $ref: '#/components/schemas/PaymentStatus'
          title: Current status
          description: >-
            See the payment [status table](../docs#payment-status) for more
            information.
        orderId:
          title: Order ID
          type: string
          description: Your reference for the payment.
        processor:
          $ref: '#/components/schemas/PaymentSummaryProcessorAPISchema'
          title: Processor
          description: The payment processor used for this payment.
        currencyCode:
          title: Currency
          type: string
          description: >
            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:
          title: Payment amount
          type: integer
          format: int64
          description: The payment amount, in minor units. e.g. $7 would show as `700`.
        metadata:
          title: Payment Metadata
          type: object
          description: >
            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"}`
      example:
        id: IHQlakKC
        date: '2021-03-24T14:56:56.869248'
        status: SETTLED
        orderId: my-order-123
        currencyCode: EUR
        amount: 700
        processor:
          name: STRIPE
          processorMerchantId: acct_stripe_1234
        metadata:
          productId: 123
          merchantId: a13bsd62s
    ErrorObject:
      title: Error
      type: object
      description: An object containing information about the error that occurred.
      required:
        - errorId
        - description
      properties:
        errorId:
          title: Error ID
          type: string
          description: An error ID
        description:
          title: Error description
          type: string
          description: A human readable description of the error
        recoverySuggestion:
          title: Recovery Suggestion
          type: string
          description: A suggestion on how to recover from the error.
        diagnosticsId:
          title: Error diagnostics ID
          type: string
          description: >-
            An ID that you can quote when contacting the Primer support team via
            our [Support
            Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
        validationErrors:
          title: Validation Errors
          type: array
          items:
            type: object
          description: Returned in case of a badly formed request
    PaymentSummaryProcessorAPISchema:
      title: PaymentSummaryProcessorAPISchema
      required:
        - name
      type: object
      properties:
        name:
          title: Processor Name
          type: string
          description: The payment processor used for this payment.
        processorMerchantId:
          title: Processor Merchant ID
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this
            payment.
  parameters:
    ApiVersionHeader:
      required: true
      schema:
        title: X-API-VERSION
        type: string
        example: '2.4'
      name: X-API-VERSION
      description: Specifies the version of the API to use. This must be set to `2.4`.
      in: header
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````