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

# List transactions

> Lists transactions for the company in `X-On-Behalf-Of`, newest first by `transaction_at`.
Results are limited to the accounts the API key's member can access.

By default the list excludes future-scheduled payments and the internal reward types
`loyalty_out`, `points_in`, `points_out`, and `trophy`. Pass `type` to include a
specific type, or `ids` / `source_payment_ids` to look up rows regardless of these defaults.

Use cursor pagination (`next_cursor` → `cursor`) for large result sets. Offset pagination
(`offset`) also returns a `total` count but cannot be combined with `cursor`.




## OpenAPI

````yaml /specs/company.openapi.yaml get /developer/transactions
openapi: 3.1.0
info:
  title: Incard Developer API
  version: 0.1.0
  description: OpenAPI definition for the Incard Developer API.
servers:
  - url: https://api.incard.com
    description: Developer Gateway
security:
  - BearerAuth: []
tags:
  - name: ACCOUNTS
    description: Currency accounts and their available balances.
  - name: TRANSACTIONS
    description: Transaction history with filters, pagination, and running balances.
  - name: CARDS
    description: List cards and freeze or unfreeze them.
  - name: INVOICES
  - name: webhooks
paths:
  /developer/transactions:
    get:
      tags:
        - TRANSACTIONS
      summary: List transactions
      description: >
        Lists transactions for the company in `X-On-Behalf-Of`, newest first by
        `transaction_at`.

        Results are limited to the accounts the API key's member can access.


        By default the list excludes future-scheduled payments and the internal
        reward types

        `loyalty_out`, `points_in`, `points_out`, and `trophy`. Pass `type` to
        include a

        specific type, or `ids` / `source_payment_ids` to look up rows
        regardless of these defaults.


        Use cursor pagination (`next_cursor` → `cursor`) for large result sets.
        Offset pagination

        (`offset`) also returns a `total` count but cannot be combined with
        `cursor`.
      operationId: list_transactions
      parameters:
        - name: account_ids
          in: query
          required: false
          description: Comma-separated account UUIDs to include.
          schema:
            type: string
          example: 0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c
        - name: account_currencies
          in: query
          required: false
          description: Comma-separated ISO 4217 account currencies (for example `GBP,EUR`).
          schema:
            type: string
        - name: transaction_currencies
          in: query
          required: false
          description: Comma-separated ISO 4217 currencies the transaction was made in.
          schema:
            type: string
        - name: ids
          in: query
          required: false
          description: >-
            Comma-separated transaction UUIDs. Explicit lookups bypass the
            default type and scheduled exclusions.
          schema:
            type: string
        - name: source_payment_ids
          in: query
          required: false
          description: >-
            Comma-separated identifiers of the payment in the originating source
            system.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: >-
            Comma-separated statuses. One or more of `pending`, `completed`,
            `declined`, `reversed`.
          schema:
            type: string
          example: completed,pending
        - name: type
          in: query
          required: false
          description: >-
            Comma-separated transaction types. See the `type` field on the
            transaction object for values.
          schema:
            type: string
          example: card,out
        - name: direction
          in: query
          required: false
          description: Comma-separated directions. One or both of `debit`, `credit`.
          schema:
            type: string
        - name: user_ids
          in: query
          required: false
          description: Comma-separated UUIDs of the users who initiated the transactions.
          schema:
            type: string
        - name: payee_ids
          in: query
          required: false
          description: Comma-separated payee identifiers.
          schema:
            type: string
        - name: card_tokens
          in: query
          required: false
          description: >-
            Comma-separated card tokens. Returns card transactions made with
            those cards.
          schema:
            type: string
        - name: category_ids
          in: query
          required: false
          description: Comma-separated category UUIDs.
          schema:
            type: string
        - name: categorized
          in: query
          required: false
          description: >-
            `true` returns only categorised transactions, `false` only
            uncategorised.
          schema:
            type: boolean
        - name: q
          in: query
          required: false
          description: Case-insensitive substring match against `name` and `reference`.
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Inclusive lower bound on `transaction_at` (RFC 3339).
          schema:
            type: string
            format: date-time
          example: '2026-07-01T00:00:00Z'
        - name: to
          in: query
          required: false
          description: >-
            Inclusive upper bound on `transaction_at` (RFC 3339). Must not be
            before `from`.
          schema:
            type: string
            format: date-time
          example: '2026-07-31T23:59:59Z'
        - name: account_amount_min
          in: query
          required: false
          description: Minimum absolute account amount (decimal string).
          schema:
            type: string
          example: '10.00'
        - name: account_amount_max
          in: query
          required: false
          description: >-
            Maximum absolute account amount (decimal string). Must not be less
            than `account_amount_min`.
          schema:
            type: string
          example: '500.00'
        - name: scheduled
          in: query
          required: false
          description: >-
            `true` returns only payments scheduled for today or later. `false`
            (default) excludes them.
          schema:
            type: boolean
        - name: earned_points
          in: query
          required: false
          description: >-
            `true` returns only transactions that earned points and adds
            `points_totals_by_day` to the response.
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          description: Sort field. Defaults to `transaction_at`.
          schema:
            type: string
            enum:
              - transaction_at
              - completed_at
              - authorized_at
              - created_at
        - name: order
          in: query
          required: false
          description: Sort order. Defaults to `desc`.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: limit
          in: query
          required: false
          description: Page size, 1–200. Defaults to 50.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: cursor
          in: query
          required: false
          description: >-
            Opaque `next_cursor` value from a previous page. Cannot be combined
            with `offset`.
          schema:
            type: string
        - name: offset
          in: query
          required: false
          description: >-
            Number of rows to skip. Enables the `total` count. Cannot be
            combined with `cursor`.
          schema:
            type: integer
            minimum: 0
        - name: user
          in: query
          required: false
          description: >-
            `true` includes a `user` object (name and avatar) on each
            transaction that has a `user_id`.
          schema:
            type: boolean
        - name: card
          in: query
          required: false
          description: >-
            `true` includes a `card` object (name, last four digits, type) on
            each card transaction.
          schema:
            type: boolean
      responses:
        '200':
          description: One page of transactions.
          content:
            application/json:
              schema:
                type: object
                title: TransactionCollection
                properties:
                  transactions:
                    description: Transactions for the current page.
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  next_cursor:
                    description: >-
                      Opaque cursor for the next page. Omitted on the last page
                      or when using `offset`.
                    type: string
                  total:
                    description: >-
                      Total matching transactions. Present only when `offset` is
                      supplied.
                    type: integer
                  points_totals_by_day:
                    description: >-
                      Present only when `earned_points=true`. Points earned per
                      day for the current page.
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          description: Calendar day (`YYYY-MM-DD`).
                          type: string
                        points:
                          description: Points earned on that day.
                          type: integer
                required:
                  - transactions
              example:
                transactions:
                  - id: 342ea759-8870-418a-aa4c-ebc3a93ff70d
                    source_payment_id: ab8861be-020f-6449-655e-c7b00ff71b74
                    reference: Sent from Incard
                    payee_id: 6992e50e-dfd7-4d9c-891c-362ccfc01b58
                    payee_route: local
                    company_id: bebb185d-8210-4e66-ac63-397b49a1e09f
                    account_id: 0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c
                    name: ACME Corp
                    status: completed
                    type: out
                    direction: debit
                    authorized_at: '2026-07-02T16:07:39.942Z'
                    completed_at: '2026-07-02T16:08:11.104Z'
                    transaction_at: '2026-07-02T16:07:39.917Z'
                    account_amount:
                      value: '-300.00'
                      currency: GBP
                    transaction_amount:
                      value: '-300.00'
                      currency: GBP
                    base_amount:
                      value: '-300.00'
                      currency: GBP
                    running_balance:
                      value: '4700.00'
                      currency: GBP
                    user_id: 29b297ca-c617-437e-9c1d-32f494fbf44d
                    created_at: '2026-07-02T16:07:39.970773Z'
                    updated_at: '2026-07-02T16:08:11.120114Z'
                  - id: 7f3c2a10-5d4e-4b8a-9c1d-2e3f4a5b6c7d
                    source_payment_id: 9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b
                    company_id: bebb185d-8210-4e66-ac63-397b49a1e09f
                    account_id: 0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c
                    name: Amazon
                    status: pending
                    type: card
                    direction: debit
                    authorized_at: '2026-07-01T09:12:03.000Z'
                    transaction_at: '2026-07-01T09:12:03.000Z'
                    account_amount:
                      value: '-42.50'
                      currency: GBP
                    transaction_amount:
                      value: '-49.99'
                      currency: EUR
                    base_amount:
                      value: '-42.50'
                      currency: GBP
                    fx_rate: '1.176235'
                    running_balance:
                      value: '5000.00'
                      currency: GBP
                    raw_merchant:
                      online: true
                      merchant_city: LUXEMBOURG
                      merchant_country: LU
                      mcc: '5942'
                    merchant_id: amazon
                    enriched_merchant:
                      icon_url: https://cdn.incard.com/merchants/amazon.png
                      category: Shopping
                      display_name: Amazon
                    category_id: 883b6c21-9210-4e4a-9abe-3d9960face91
                    user_id: 29b297ca-c617-437e-9c1d-32f494fbf44d
                    card_token: 84de8ea0-e52a-4888-afd2-9d8dd5a42c20
                    created_at: '2026-07-01T09:12:03.412Z'
                    updated_at: '2026-07-01T09:12:03.412Z'
                next_cursor: >-
                  eyJzb3J0IjoidHJhbnNhY3Rpb25fYXQiLCJkaXJlY3Rpb24iOiJkZXNjIiwidmFsdWUiOiIyMDI2LTA3LTAxVDA5OjEyOjAzWiIsImlkIjoiN2YzYzJhMTAtNWQ0ZS00YjhhLTljMWQtMmUzZjRhNWI2YzdkIn0
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionError'
              example:
                error: limit must be between 1 and 200
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — insufficient permission for this user
components:
  schemas:
    Transaction:
      type: object
      title: Transaction
      description: >
        A transaction on one of the company's accounts. Optional fields are
        omitted from the JSON when they have no value.

        Amounts are signed: `debit` transactions carry negative values, `credit`
        transactions positive values.
      properties:
        id:
          description: >-
            Transaction UUID. Stable across status changes and matches the
            `data.id` in transaction webhooks.
          type: string
        source_payment_id:
          description: Identifier of the payment in the originating source system.
          type: string
        company_id:
          description: Company UUID that owns the transaction.
          type: string
        account_id:
          description: UUID of the account the transaction belongs to.
          type: string
        related_account_id:
          description: >-
            (Optional) For `transfer_*` and `exchange_*` types, the other
            company account involved.
          type: string
        name:
          description: Human-readable label (merchant, payee, or sender name).
          type: string
        status:
          description: >-
            Lifecycle status. `pending` transitions to `completed`, `declined`,
            or `reversed`; the other states are terminal.
          type: string
          enum:
            - pending
            - completed
            - declined
            - reversed
        type:
          description: Transaction type.
          type: string
          enum:
            - card
            - atm
            - refund
            - credit
            - out
            - in
            - fee
            - exchange_out
            - exchange_in
            - transfer_out
            - transfer_in
            - chargeback
            - reversal
            - adjustment
            - loyalty_in
            - loyalty_out
            - points_in
            - points_out
            - trophy
            - referral
            - direct_debit
            - direct_credit
            - direct_credit_return
            - recall
        direction:
          description: '`debit` for money leaving the account, `credit` for money arriving.'
          type: string
          enum:
            - debit
            - credit
        reference:
          description: (Optional) Free-text payment reference.
          type: string
        payee_id:
          description: (Optional) Payee identifier for outbound payments.
          type: string
        payee_route:
          description: (Optional) Payment rail used, for example `local`.
          type: string
        purpose_code:
          description: (Optional) Payment purpose code where the rail requires one.
          type: string
        provider:
          description: (Optional) Underlying payment provider.
          type: string
        recon_ref:
          description: (Optional) Reconciliation reference from the provider.
          type: string
        authorized_at:
          description: (Optional) When the transaction was authorised.
          type: string
          format: date-time
        completed_at:
          description: >-
            (Optional) When the transaction settled. Set once `status` is
            `completed`.
          type: string
          format: date-time
        scheduled_for:
          description: >-
            (Optional) For scheduled payments, when the payment is due to
            execute.
          type: string
          format: date-time
        transaction_at:
          description: When the transaction occurred. Default sort key.
          type: string
          format: date-time
        account_amount:
          description: >-
            Signed amount in the account currency. `null` only for rows with no
            amount yet.
          oneOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        fee_amount:
          $ref: '#/components/schemas/Money'
          description: >-
            (Optional) Fee charged, as a negative amount in the account
            currency. Omitted when zero.
        transaction_amount:
          $ref: '#/components/schemas/Money'
          description: >-
            (Optional) Signed amount in the currency the transaction was made
            in.
        base_amount:
          $ref: '#/components/schemas/Money'
          description: (Optional) Signed amount in the company's base currency.
        fx_rate:
          description: >-
            (Optional) `transaction_amount / account_amount`, present only when
            the two currencies differ. Six decimal places.
          type: string
        running_balance:
          description: >-
            Posted ledger balance of the account immediately after this
            transaction, ordered by `transaction_at`. Excludes pending holds.
          oneOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
        points:
          description: (Optional) Reward points earned or redeemed.
          type: integer
        raw_merchant:
          description: (Optional) Merchant details as received from the card network.
          type: object
          properties:
            online:
              description: Whether the purchase was made online.
              type: boolean
            merchant_city:
              type: string
            merchant_country:
              description: ISO 3166-1 alpha-2 country code.
              type: string
            merchant_street:
              type: string
            merchant_region:
              type: string
            merchant_postcode:
              type: string
            mcc:
              description: Merchant category code.
              type: string
        merchant_id:
          description: >-
            (Optional) Incard merchant identifier once the merchant has been
            recognised.
          type: string
        enriched_merchant:
          description: (Optional) Display details for a recognised merchant.
          type: object
          properties:
            icon_url:
              type: string
            category:
              type: string
            display_name:
              type: string
        category_id:
          description: (Optional) Spend category UUID.
          type: string
        accounting_code:
          description: (Optional) Accounting code assigned to the transaction.
          type: object
          properties:
            provider:
              description: Accounting provider, for example `xero`.
              type: string
            id:
              type: string
            name:
              type: string
            code:
              type: integer
        user_id:
          description: (Optional) UUID of the user who initiated the transaction.
          type: string
        user:
          description: (Optional) Included when `user=true` and `user_id` is set.
          type: object
          properties:
            first_name:
              type: string
            last_name:
              type: string
            icon_url:
              type: string
        card_token:
          description: (Optional) Token of the card used, for `card` and `atm` types.
          type: string
        card:
          description: (Optional) Included when `card=true` and `card_token` is set.
          type: object
          properties:
            id:
              description: Card UUID.
              type: string
            name:
              description: Card name.
              type: string
            last4:
              description: Last four digits of the PAN.
              type: string
            theme:
              description: Card theme, or `null`.
              type:
                - string
                - 'null'
            type:
              description: Card type, for example `virtual` or `physical`.
              type: string
        trophy_id:
          description: (Optional) Trophy UUID for `trophy` rewards.
          type: string
        decline_reason:
          description: (Optional) Reason the transaction was declined.
          type: string
        note:
          description: (Optional) Note added by a team member.
          type: string
        created_at:
          description: When the transaction record was created.
          type: string
          format: date-time
        updated_at:
          description: When the transaction record was last updated.
          type: string
          format: date-time
      required:
        - id
        - source_payment_id
        - company_id
        - account_id
        - name
        - status
        - type
        - direction
        - transaction_at
        - account_amount
        - running_balance
        - created_at
        - updated_at
    TransactionError:
      type: object
      title: TransactionError
      properties:
        error:
          description: Human-readable error message.
          type: string
      required:
        - error
    Money:
      type: object
      title: Money
      description: A signed decimal amount with its currency.
      properties:
        value:
          description: >-
            Decimal amount as a string with two decimal places. Negative for
            money leaving the account.
          type: string
        currency:
          description: ISO 4217 currency code.
          type: string
      required:
        - value
        - currency
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
      description: Short-lived access token. Obtain with your api_key.

````