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

# List payments

> Returns a paginated list of payments, sorted by creation time in
descending order (newest first). If no payments match the filters, the
response is `200 OK` with an empty `data` array.




## OpenAPI

````yaml /api-reference/payments-api.yaml get /v1/payments
openapi: 3.0.4
info:
  title: Flowlix Payments API
  version: 1.0.0
  description: >
    The Flowlix Payments API is a RESTful API for creating and retrieving

    Payments, creating Refunds, and submitting and retrieving Payouts.

    It follows industry-standard conventions: JSON request/response bodies,
    Bearer token authentication,

    standard HTTP verbs, idempotency support, and cursor-based pagination.


    ## Base URL


    API requests are made to `https://api.flowlix.eu`.

    Endpoints are versioned under `/v1`, e.g.

    `https://api.flowlix.eu/v1/payments`.


    ## Amounts and currencies


    All monetary amounts are expressed in **minor units** (the smallest currency
    unit).

    How many minor units make up one major unit is defined by the currency's

    ISO 4217 exponent, so the same integer means a different value in different

    currencies: `4999` is **EUR 49.99** and **GBP 49.99** (exponent 2), but

    **JPY 4999** (exponent 0, no minor unit). Do not assume two decimal places.


    Currencies are three-letter ISO 4217 codes. Requests are accepted

    case-insensitively; Flowlix normalizes them and always returns canonical

    uppercase codes such as `EUR`. The currencies accepted for a Payment or

    Payout are validated separately per request rather than listed in this

    contract, so enabling another currency is not a breaking change. A code

    that is not three letters is rejected with `400 parameter_invalid`

    (`param=currency`), and a well-formed code that Flowlix does not accept for

    the requested operation is rejected with `422 currency_not_supported`.

    Neither response creates a Payment or Payout.


    A refund is always made in the currency of the original payment, and the

    refund request does not accept a currency.
  contact:
    name: Flowlix Developer Support
    email: developers@flowlix.eu
    url: https://flowlix.dev/support
  license:
    name: Proprietary
    url: https://flowlix.dev/terms
servers:
  - url: https://api.flowlix.eu
    description: Flowlix Merchant API.
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Check aggregate Flowlix API availability.
  - name: Payments
    description: Create, retrieve, and list payments.
  - name: Payouts
    description: Submit, list, and retrieve Host-to-Host card payouts.
  - name: Refunds
    description: >-
      Create refunds and track their status through the parent payment's
      `refunds` array.
paths:
  /v1/payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: |
        Returns a paginated list of payments, sorted by creation time in
        descending order (newest first). If no payments match the filters, the
        response is `200 OK` with an empty `data` array.
      operationId: listPayments
      parameters:
        - name: limit
          in: query
          description: >-
            Maximum number of payments to return. Accepts values between 1 and
            100.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 25
        - name: starting_after
          in: query
          description: |
            Cursor for forward pagination. Provide the `id` of the last payment
            in the previous page. Mutually exclusive with `ending_before`.
          required: false
          schema:
            $ref: '#/components/schemas/PaymentId'
        - name: ending_before
          in: query
          description: >
            Cursor for backward pagination. Provide the `id` of the first

            payment in the current page. Mutually exclusive with
            `starting_after`.
          required: false
          schema:
            $ref: '#/components/schemas/PaymentId'
        - name: status
          in: query
          description: >
            Filter payments by status. `FAILED` also includes payments whose

            status is `EXPIRED`. Each returned Payment's `status` remains
            authoritative.
          required: false
          schema:
            $ref: '#/components/schemas/PaymentStatus'
        - name: created_gte
          in: query
          description: Return payments created on or after this Unix timestamp in seconds.
          required: false
          schema:
            type: integer
            format: int64
          example: 1719792000
        - name: created_lt
          in: query
          description: Return payments created before this Unix timestamp in seconds.
          required: false
          schema:
            type: integer
            format: int64
          example: 1719878400
      responses:
        '200':
          description: |
            Matching payments, sorted newest first. An empty `data` array means
            no payments match the supplied filters.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
              examples:
                page:
                  $ref: '#/components/examples/PaymentListPage'
        '400':
          $ref: '#/components/responses/PaymentListBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    PaymentId:
      type: string
      pattern: ^pay_[A-Za-z0-9]{24}$
      description: >-
        Unique opaque identifier for a payment (`pay_` prefix + random
        alphanumeric suffix).
      example: pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E
    PaymentStatus:
      type: string
      enum:
        - PENDING
        - REQUIRES_ACTION
        - PROCESSING
        - SUCCEEDED
        - FAILED
        - EXPIRED
      description: >
        Current status of a payment attempt.


        - `PENDING` -- The payment was accepted by Flowlix and is awaiting
        provider submission or the next lifecycle decision.

        - `REQUIRES_ACTION` -- Customer action is required, such as completing
        3D Secure authentication or a hosted payment page.

        - `PROCESSING` -- The payment is being processed by downstream payment
        systems.

        - `SUCCEEDED` -- The payment completed successfully.

        - `FAILED` -- The payment was declined or failed permanently.

        - `EXPIRED` -- The customer did not complete a required action before
        its expiry time.
      example: SUCCEEDED
    PaymentList:
      type: object
      description: Paginated list of payments.
      required:
        - data
        - has_more
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        has_more:
          type: boolean
          description: Whether more payments are available after this page.
          example: false
    Payment:
      type: object
      description: |
        A Payment represents one attempt to collect funds from the customer.
        Merchants can use `merchant_reference` to associate multiple
        payment attempts with the same order or checkout in their own systems.
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - livemode
        - amount_refunded
        - amount_refundable
        - integration_type
      properties:
        id:
          $ref: '#/components/schemas/PaymentId'
        amount:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Payment amount in the currency's minor units, per its ISO 4217
            exponent: `4999` is EUR 49.99 but JPY 4999.
          example: 4999
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        integration_type:
          $ref: '#/components/schemas/IntegrationType'
        merchant_reference:
          type: integer
          allOf:
            - $ref: '#/components/schemas/MerchantReference'
          nullable: true
          description: Merchant-side reconciliation reference, if provided.
        description:
          type: string
          nullable: true
          description: Merchant-provided payment description.
          example: 'Order #1234'
        card:
          type: object
          allOf:
            - $ref: '#/components/schemas/Card'
          nullable: true
          description: Masked card details, or `null` before card details are available.
        billing_details:
          type: object
          allOf:
            - $ref: '#/components/schemas/BillingDetails'
          nullable: true
          description: Billing details captured for the payment, if available.
        failure_code:
          type: string
          allOf:
            - $ref: '#/components/schemas/OperationFailureCode'
          nullable: true
          description: >-
            Machine-readable reason code when the payment reaches a terminal
            failed status.
          example: insufficient_funds
        failure_message:
          type: string
          nullable: true
          description: >-
            Human-readable explanation when the payment reaches a terminal
            failed status.
          example: The card has insufficient funds.
        amount_refunded:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Total amount successfully refunded so far, in the payment currency's
            minor units, per its ISO 4217 exponent.
          example: 0
        amount_refundable:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Remaining amount that can be refunded, in the payment currency's
            minor units, per its ISO 4217 exponent.
          example: 4999
        refunds:
          type: array
          description: Refunds created for this payment, oldest first.
          items:
            $ref: '#/components/schemas/Refund'
          default: []
        status_transitions:
          $ref: '#/components/schemas/StatusTransitions'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the payment was created.
          example: 1719792000
        livemode:
          type: boolean
          description: Always `false` for a Payment created in Sandbox.
          example: false
        next_action:
          type: object
          allOf:
            - $ref: '#/components/schemas/PaymentNextAction'
          nullable: true
          description: Customer action required to continue the payment.
    ApiError:
      type: object
      description: Error response wrapper.
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
    CurrencyCode:
      type: string
      minLength: 3
      maxLength: 3
      pattern: ^[A-Z]{3}$
      description: >
        Canonical uppercase three-letter ISO 4217 currency code. Responses
        always

        return the original currency the payment was created in; a provider

        response never replaces it.
      example: EUR
    IntegrationType:
      type: string
      enum:
        - DIRECT
        - HOSTED_PAYMENT_PAGE
      description: |
        How the payment was collected. This is separate from the payment method
        instrument, such as `card`.
      example: DIRECT
    MerchantReference:
      type: integer
      format: int64
      minimum: 1000000000
      maximum: 9999999999
      description: |
        Optional merchant-side reconciliation reference. The value must contain
        exactly 10 decimal digits and does not provide idempotency by itself.
      example: 1234567890
    Card:
      type: object
      description: >-
        Masked card details. If card details are not available, the entire
        `card` field is `null`.
      required:
        - brand
        - last4
        - exp_month
        - exp_year
      properties:
        brand:
          $ref: '#/components/schemas/CardBrand'
        last4:
          type: string
          pattern: ^[0-9]{4}$
          description: Last four digits of the card number.
          example: '2207'
        exp_month:
          type: integer
          format: int32
          minimum: 1
          maximum: 12
          description: Card expiration month.
          example: 12
        exp_year:
          type: integer
          format: int32
          description: Card expiration year.
          example: 2027
        cardholder_name:
          type: string
          nullable: true
          description: >-
            Cardholder name, if available. For Direct API payments, this is the
            submitted `holder_name`.
          example: Jenny Rosen
        country:
          type: string
          nullable: true
          description: Two-letter ISO country code of the issuing bank, if available.
          allOf:
            - $ref: '#/components/schemas/CountryCode'
    BillingDetails:
      type: object
      description: Billing details associated with the payer.
      properties:
        email:
          type: string
          nullable: true
          format: email
          description: Billing email address.
          example: jenny@example.com
        first_name:
          type: string
          nullable: true
          description: Payer first name.
          example: Jenny
        last_name:
          type: string
          nullable: true
          description: Payer last name.
          example: Rosen
        phone:
          type: string
          nullable: true
          pattern: ^\+[1-9]\d{1,14}$
          description: Billing phone number in E.164 format, for example `+491701234567`.
          example: '+491701234567'
        address:
          type: object
          allOf:
            - $ref: '#/components/schemas/BillingAddress'
          nullable: true
    OperationFailureCode:
      type: string
      description: >-
        Stable public failure vocabulary used by Payment `failure_code`, Refund
        `failure.code`, and Payout `failure_code`. The meaning is shared, but
        handling differs: shopper or new-card actions for a Payment must not be
        applied to a Refund or Payout.
      enum:
        - not_found
        - processor_error
        - processor_unavailable
        - generic_decline
        - do_not_honor
        - issuer_declined
        - insufficient_funds
        - invalid_number
        - invalid_expiry
        - expired_card
        - invalid_amount
        - invalid_currency
        - not_permitted
        - cardholder_limit
        - card_velocity_exceeded
        - lost_card
        - stolen_card
        - suspect_fraud
        - fraud_filter
        - three_d_secure_failed
        - three_d_secure_timeout
        - three_d_secure_not_supported
        - three_d_secure_error
      example: insufficient_funds
    Refund:
      type: object
      description: A refund against a payment.
      required:
        - id
        - payment_id
        - amount
        - currency
        - reason
        - refund_type
        - status
        - created_at
        - updated_at
        - livemode
      properties:
        id:
          $ref: '#/components/schemas/RefundId'
        payment_id:
          $ref: '#/components/schemas/PaymentId'
        amount:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Refund amount in the currency's minor units, per its ISO 4217
            exponent: `4999` is EUR 49.99 but JPY 4999.
          example: 1500
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        merchant_reference:
          type: integer
          allOf:
            - $ref: '#/components/schemas/MerchantReference'
          nullable: true
          description: Merchant-side reconciliation reference for this refund, if provided.
        reason:
          type: string
          maxLength: 50
          description: Merchant-provided refund reason stored with the refund.
          example: Full refund verification
        refund_type:
          $ref: '#/components/schemas/RefundType'
        status:
          $ref: '#/components/schemas/RefundStatus'
        failure:
          $ref: '#/components/schemas/RefundFailure'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when the refund was created.
          example: 1719795600
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when the refund was last updated.
          example: 1719795660
        completed_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the refund reached a terminal status.
          example: 1719799200
        livemode:
          type: boolean
          description: Always `false` for a Refund created in Sandbox.
          example: false
    StatusTransitions:
      type: object
      description: Timestamps for important payment status transitions.
      properties:
        requires_action_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment first required customer action.
          example: null
        processing_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when downstream processing started.
          example: 1719792002
        succeeded_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment succeeded.
          example: 1719792042
        failed_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment failed.
          example: null
        expired_at:
          type: integer
          nullable: true
          format: int64
          description: Unix timestamp when the payment expired.
          example: null
    PaymentNextAction:
      type: object
      required:
        - type
        - reason
        - redirect_url
      properties:
        type:
          type: string
          enum:
            - redirect
          description: The action type. Currently only `redirect` is supported.
          example: redirect
        reason:
          type: string
          enum:
            - hosted_payment_page
            - three_d_secure
          description: Why the customer redirect is required.
          example: three_d_secure
        redirect_url:
          type: string
          format: uri
          description: |
            Opaque provider URL for the current customer browser action. The
            URL can point to a hosted payment page, 3D Secure fingerprint
            collection, or a later authentication/challenge step. Redirect the
            customer to the latest URL returned for the payment, follow a new
            URL if it changes while the payment is still `REQUIRES_ACTION`, and
            avoid repeatedly redirecting the same browser to the same URL.
          example: https://authentication.example/redirect-token
    ApiErrorBody:
      type: object
      description: Detailed error information.
      required:
        - message
      properties:
        code:
          type: string
          nullable: true
          description: Short machine-readable error code.
        message:
          type: string
          description: >-
            Human-readable context that may include object-specific values and
            may change. Branch on `code`, not this text.
        param:
          type: string
          nullable: true
          description: Request parameter that caused the error, if applicable.
        doc_url:
          type: string
          nullable: true
          format: uri
          description: URL to documentation for this error.
        request_id:
          type: string
          nullable: true
          description: Request ID matching the `Request-Id` response header.
    CardBrand:
      type: string
      description: |
        Canonical lower-case card-network brand, for example `visa`,
        `mastercard`, or `amex`. The schema remains extensible; each operation
        validates its supported brands separately.
      example: visa
    CountryCode:
      type: string
      pattern: ^[A-Z]{2}$
      description: Canonical ISO 3166-1 alpha-2 country code.
      example: DE
    BillingAddress:
      type: object
      description: Billing address associated with the payer.
      properties:
        line1:
          type: string
          nullable: true
          description: First line of the billing street address.
          example: Kurfuerstendamm 21
        line2:
          type: string
          nullable: true
          description: Second line of the billing street address, if present.
          example: Apartment 4B
        city:
          type: string
          nullable: true
          description: Billing city.
          example: Berlin
        state:
          type: string
          nullable: true
          description: Billing state, region, or province, if applicable.
          example: Berlin
        postal_code:
          type: string
          nullable: true
          description: Billing postal code.
          example: '10719'
        country:
          type: string
          nullable: true
          pattern: ^[A-Z]{2}$
          description: Billing country as an ISO 3166-1 alpha-2 code.
          example: DE
    RefundId:
      type: string
      pattern: ^ref_[A-Za-z0-9]{24}$
      description: >-
        Unique opaque identifier for a refund (`ref_` prefix + random
        alphanumeric suffix).
      example: ref_L9xQ4wE2rT8yU6iO3pA7sD1f
    RefundType:
      type: string
      enum:
        - FULL
        - PARTIAL
      description: |
        Whether the refund covers the full original payment amount or only part
        of it.
      example: FULL
    RefundStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - SUCCEEDED
        - FAILED
      description: |
        Current refund lifecycle status. Refunds normally move from `PENDING`
        to `PROCESSING`, then to `SUCCEEDED` or `FAILED`.
      example: PENDING
    RefundFailure:
      type: object
      nullable: true
      description: Refund failure details when the refund reaches `FAILED`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable Flowlix error code.
          example: fraud_filter
        message:
          type: string
          description: Human-readable Flowlix error explanation.
          example: The payment was declined by fraud controls.
  headers:
    RequestId:
      description: >-
        A unique identifier for this API request. Include it when contacting
        support.
      schema:
        type: string
        maxLength: 255
      example: req_abc123def456
    RetryAfter:
      description: Number of seconds to wait before retrying.
      schema:
        type: integer
      example: 5
  examples:
    PaymentListPage:
      summary: Page containing one succeeded Payment
      value:
        data:
          - id: pay_t0Np5Qs1Yu7Aw9Bc2De6Fg8H
            amount: 4999
            currency: EUR
            status: SUCCEEDED
            integration_type: DIRECT
            merchant_reference: 1234567890
            amount_refunded: 0
            amount_refundable: 4999
            refunds: []
            created_at: 1719792000
            livemode: false
        has_more: false
    ErrorInvalidRequest:
      summary: Read request contains an invalid value
      value:
        error:
          code: invalid_request
          message: Request validation failed.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_read400a
    ErrorPaymentInvalidSearchCriteria:
      summary: Payment list cursors are incompatible
      value:
        error:
          code: invalid_search_criteria
          message: >-
            starting_after='pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E' and
            ending_before='pay_r8Ln3Oq9Ws5Yu7Za0Bc4De6F' are mutually exclusive.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_paysearch400a
    ErrorListParameterInvalid:
      summary: List query parameter has an invalid value
      value:
        error:
          code: parameter_invalid
          message: Request parameter is invalid.
          param: created_gte
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_list400a
    ErrorInvalidApiKey:
      summary: Missing or invalid API key
      value:
        error:
          code: invalid_api_key
          message: The API key is invalid.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_auth401a
    ErrorInternal:
      summary: Unexpected Flowlix error
      value:
        error:
          code: internal_error
          message: An internal error occurred.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_internal500a
    ErrorServiceUnavailable:
      summary: Flowlix is temporarily unavailable
      value:
        error:
          code: service_unavailable
          message: Upstream payment processor is temporarily unavailable. Please retry.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_service503a
  responses:
    PaymentListBadRequest:
      description: |
        A Payment list filter, cursor, or query value is invalid. Correct the
        parameter named by `error.param` when it is present.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            invalid_request:
              $ref: '#/components/examples/ErrorInvalidRequest'
            invalid_search_criteria:
              $ref: '#/components/examples/ErrorPaymentInvalidSearchCriteria'
            invalid_parameter:
              $ref: '#/components/examples/ErrorListParameterInvalid'
    Unauthorized:
      description: >
        The API key is missing, invalid, expired, or revoked. Send the secret
        key

        for the intended merchant and mode in `Authorization: Bearer <key>`.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            invalid_api_key:
              $ref: '#/components/examples/ErrorInvalidApiKey'
    InternalError:
      description: |
        Flowlix encountered an unexpected server error before the operation
        completed. Retry safely with the original idempotency key for a POST
        and include `Request-Id` when contacting support.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            internal_error:
              $ref: '#/components/examples/ErrorInternal'
    ServiceUnavailable:
      description: |
        Flowlix is temporarily unable to process the request. Wait for
        `Retry-After` when present, then retry with exponential backoff. Reuse
        the same idempotency key when retrying a POST request.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            service_unavailable:
              $ref: '#/components/examples/ErrorServiceUnavailable'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Use the secret API key for the intended merchant and mode as the Bearer
        token. Sandbox keys start with `api_test_sk_`. Send the key only from
        your server environment.

        ```
        Authorization: Bearer api_test_sk_abc123def456
        ```

````