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

# List invoice payments

> List all invoice payments for a business with filtering, pagination, and summary statistics.



## OpenAPI

````yaml GET /v1/platform/businesses/{business_id}/invoices/payments/
openapi: 3.0.3
info:
  title: Thredfi Accounting Platform API
  version: 1.0.0
  description: >-
    Comprehensive API for accounting, invoice management, open banking, and
    intelligence services.
servers: []
security: []
paths:
  /v1/platform/businesses/{business_id}/invoices/payments/:
    get:
      tags:
        - Invoice Payments
      summary: List invoice payments
      description: >-
        List all invoice payments for a business with filtering, pagination, and
        summary statistics.
      operationId: list_invoice_payments
      parameters:
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          description: Business UUID provided by Thred (unique identifier for the business)
          required: true
        - in: query
          name: customer_id
          schema:
            type: string
          description: >-
            Filter by customer ID (supports comma-separated UUIDs for multiple
            customers)
        - in: query
          name: date_from
          schema:
            type: string
            format: date-time
          description: Filter payments from this date/time (ISO format)
        - in: query
          name: date_to
          schema:
            type: string
            format: date-time
          description: Filter payments to this date/time (ISO format)
        - in: query
          name: fully_allocated
          schema:
            type: boolean
          description: >-
            Filter by allocation status (true=fully allocated,
            false=partially/unallocated)
        - in: query
          name: invoice_id
          schema:
            type: string
            format: uuid
          description: Filter by invoice ID (payments allocated to this invoice)
        - in: query
          name: max_amount
          schema:
            type: integer
          description: Maximum payment amount in cents (e.g., 100000 for €1000.00)
        - in: query
          name: method
          schema:
            type: string
          description: Filter by payment method
        - in: query
          name: min_amount
          schema:
            type: integer
          description: Minimum payment amount in cents (e.g., 10050 for €100.50)
        - in: query
          name: order
          schema:
            type: string
          description: 'Sort order (asc, desc). Default: desc'
        - in: query
          name: page
          schema:
            type: integer
          description: 'Page number (default: 1)'
        - in: query
          name: page_size
          schema:
            type: integer
          description: 'Items per page (default: 20, max: 100)'
        - in: query
          name: processor
          schema:
            type: string
          description: Filter by payment processor
        - in: query
          name: search
          schema:
            type: string
          description: >-
            Search by payment reference, external_id, processor_reference,
            bank_reference, customer name, or notes
        - in: query
          name: sort
          schema:
            type: string
          description: 'Sort field (payment_date, amount, created_at). Default: payment_date'
        - in: query
          name: status
          schema:
            type: string
          description: >-
            Filter by payment status (pending, processing, completed, failed,
            cancelled, refunded)
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvoicePaymentListList'
          description: ''
      security:
        - PartnerJWT: []
        - BusinessScopedJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    PaginatedInvoicePaymentListList:
      type: object
      required:
        - count
        - page_info
        - results
      properties:
        count:
          type: integer
          example: 123
          description: Total number of items
        page_info:
          type: object
          example:
            total_count: 123
            current_page: 1
            total_pages: 7
            page_size: 20
          required:
            - total_count
            - current_page
            - total_pages
            - page_size
          properties:
            total_count:
              type: integer
              example: 123
              description: Total number of items (same as count)
            current_page:
              type: integer
              example: 1
              description: Current page number (1-indexed)
            total_pages:
              type: integer
              example: 7
              description: Total number of pages
            page_size:
              type: integer
              example: 20
              description: Number of items per page
        results:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePaymentList'
    InvoicePaymentList:
      type: object
      description: |-
        Comprehensive serializer for invoice payments list endpoint.
        Extends PaymentSerializer with allocation details.

        Inspired by external payment APIs but adapted for Friday's architecture.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        external_id:
          type: string
          maxLength: 255
        payment_reference:
          type: string
          maxLength: 100
        processor_reference:
          type: string
          maxLength: 255
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerEmbedded'
          nullable: true
          readOnly: true
        customer_name:
          type: string
          readOnly: true
          description: Customer display name
        customer_email:
          type: string
          readOnly: true
          description: Customer email address
        payment_date:
          type: string
          format: date-time
        payment_method:
          enum:
            - bank_transfer
            - credit_card
            - debit_card
            - ach
            - check
            - cash
            - paypal
            - stripe
            - other
          type: string
          description: |-
            * `bank_transfer` - Bank Transfer
            * `credit_card` - Credit Card
            * `debit_card` - Debit Card
            * `ach` - ACH/Direct Debit
            * `check` - Check/Cheque
            * `cash` - Cash
            * `paypal` - PayPal
            * `stripe` - Stripe
            * `other` - Other
          x-spec-enum-id: 77fedb01429a0eb2
        payment_processor:
          type: string
          maxLength: 100
        currency:
          enum:
            - EUR
            - GBP
            - USD
            - SEK
            - NOK
            - DKK
            - ISK
            - MYR
            - SGD
          type: string
          description: |-
            * `EUR` - Euro
            * `GBP` - British Pound
            * `USD` - US Dollar
            * `SEK` - Swedish Krona
            * `NOK` - Norwegian Krone
            * `DKK` - Danish Krone
            * `ISK` - Icelandic Króna
            * `MYR` - Malaysian Ringgit
            * `SGD` - Singapore Dollar
          x-spec-enum-id: 7e6a70e4775b3009
        total_amount:
          type: integer
          description: Total payment amount in cents
          readOnly: true
        allocated_amount:
          type: integer
          description: Amount allocated to invoices in cents
          readOnly: true
        unallocated_amount:
          type: integer
          description: Unallocated amount remaining in cents (customer credit if positive)
          readOnly: true
        net_amount:
          type: integer
          description: Net amount after deducting all fees in cents
          readOnly: true
        processing_fee:
          type: integer
          description: Platform processing fee charged in cents
          readOnly: true
        processing_fee_cents:
          type: integer
          readOnly: true
          description: Platform processing fee charged in cents (raw database field)
        display_amount:
          type: string
          readOnly: true
          description: Human-readable payment amount with currency symbol
        status:
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
            - refunded
          type: string
          description: |-
            * `pending` - Pending
            * `processing` - Processing
            * `completed` - Completed
            * `failed` - Failed
            * `cancelled` - Cancelled
            * `refunded` - Refunded
          x-spec-enum-id: 760241f0a4b58134
        is_fully_allocated:
          type: boolean
          readOnly: true
          description: >-
            Whether payment is fully allocated to invoices (true if
            allocated_amount >= total_amount)
        is_completed:
          type: boolean
          readOnly: true
          description: Whether payment processing is completed (status='completed')
        processed_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        failed_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        failure_reason:
          type: string
        transaction_tags: {}
        metadata: {}
        notes:
          type: string
        bank_reference:
          type: string
          maxLength: 100
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePaymentAllocationDetail'
          readOnly: true
        refund_allocations:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRefundAllocationSummary'
          readOnly: true
          description: Refund allocations linked to this payment
        reconciled_bank_transactions:
          type: array
          items:
            $ref: '#/components/schemas/EntityReconciliationDetail'
          readOnly: true
          description: Bank transactions this payment is reconciled to
      required:
        - allocated_amount
        - allocations
        - created_at
        - customer
        - customer_email
        - customer_name
        - display_amount
        - failed_at
        - id
        - is_completed
        - is_fully_allocated
        - net_amount
        - payment_method
        - processed_at
        - processing_fee
        - processing_fee_cents
        - reconciled_bank_transactions
        - refund_allocations
        - total_amount
        - unallocated_amount
        - updated_at
    CustomerEmbedded:
      type: object
      description: Customer details embedded in payment and other response objects.
      properties:
        id:
          type: string
          format: uuid
          description: Customer UUID
        name:
          type: string
          description: Customer display name
        email:
          type: string
          format: email
          description: Customer email address
        company_name:
          type: string
          description: Company name
      required:
        - company_name
        - email
        - id
        - name
    InvoicePaymentAllocationDetail:
      type: object
      description: |-
        Enhanced allocation serializer with invoice status information
        for the invoice payments list endpoint
        All amounts in cents
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        invoice_id:
          type: string
          format: uuid
          readOnly: true
          description: UUID of the invoice
        invoice_number:
          type: string
          readOnly: true
          description: Invoice number (e.g., INV-0042)
        invoice_status:
          type: string
          readOnly: true
          description: Current invoice status (sent, paid, overdue, etc.)
        amount:
          type: integer
          description: Amount allocated to this invoice in cents
          readOnly: true
        allocated_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when allocation was created
        transaction_tags: {}
        notes:
          type: string
      required:
        - allocated_at
        - amount
        - id
        - invoice_id
        - invoice_number
        - invoice_status
    PaymentRefundAllocationSummary:
      type: object
      description: >-
        Refund allocation summary for payment detail view - shows refunds that
        used this payment.
      properties:
        refund_id:
          type: string
          format: uuid
        reference_number:
          type: string
        amount_cents:
          type: integer
        allocated_at:
          type: string
          format: date-time
      required:
        - allocated_at
        - amount_cents
        - refund_id
    EntityReconciliationDetail:
      type: object
      description: >-
        Which bank transaction an entity (invoice/bill payment) is reconciled
        to.
      properties:
        payment_type:
          type: string
        bank_transaction_id:
          type: string
          format: uuid
        bank_transaction_date:
          type: string
          format: date-time
        bank_transaction_amount_cents:
          type: integer
        bank_transaction_direction:
          type: string
        reconciled_amount_cents:
          type: integer
        reconciliation_link_id:
          type: string
          format: uuid
        reconciled_at:
          type: string
          format: date-time
        currency:
          type: string
        bank_account_name:
          type: string
        notes:
          type: string
      required:
        - bank_transaction_amount_cents
        - bank_transaction_date
        - bank_transaction_direction
        - bank_transaction_id
        - currency
        - reconciled_amount_cents
        - reconciled_at
        - reconciliation_link_id
  securitySchemes:
    PartnerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner-level JWT token (unscoped). Token payload includes `partner_id`.
        Business access is validated via partner ownership. Format: `Bearer
        <your-jwt-token>`


        **Use this for**: Multi-business operations where the business_id is
        specified in the URL and partner has access to multiple businesses.
    BusinessScopedJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT token. Token payload includes `business_id` to
        automatically scope requests. Format: `Bearer <your-jwt-token>`


        **Use this for**: Business-specific operations where the business
        context is embedded in the token.
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key
        as username:password. Example: Authorization: Basic
        base64(partner_uuid:api_key)
    BearerUnscoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner (unscoped) JWT Bearer token. Obtain via POST
        /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use
        header: Authorization: Bearer {access_token}
    BearerBusinessScoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT Bearer token. Obtain via POST
        /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token.
        Only valid for endpoints whose URL contains that business_id.

````