---
title: "Search transactions for a merchant with filtering and sorting"
method: POST
path: "/api/v1/merchants/{id}/transactions"
tags: ["Transactions"]
---

# Search transactions for a merchant with filtering and sorting

`POST /api/v1/merchants/{id}/transactions`

Search transactions for a merchant with filtering and sorting

## Path parameters

- `id` string, uuid, required — The unique identifier of the merchant

## Request body

- SearchRequest — Phase 1 transaction search with currency totals and enhanced filtering
  - `search` object — Search criteria for filtering transactions
    - `id` object — UUID filter for exact matching of payment request IDs
      - `eq` string, uuid, required — Exact match for payment request ID
    - `amount` object — Amount filter with range operations
      - `gt` number — Greater than this amount
      - `lt` number — Less than this amount
      - `gte` number — Greater than or equal to this amount
      - `lte` number — Less than or equal to this amount
      - `between` number[] — Amount range [min, max]
    - `status` object — Status filter — use eq for single status, in for multiple
      - `eq` 'completed' | 'failed' | 'cancelled' | 'pending' | 'processing' | 'error' | 'refunding' | 'refunding_stuck' | 'refunding_failed' | 'partially_refunded' | 'fully_refunded' — Exact match for transaction status
      - `in` string[] — Match any of the specified statuses
    - `transaction_type` object — Transaction type filter — use eq for single type, in for multiple
      - `eq` 'payment' | 'refund' — Exact match for transaction type
      - `in` string[] — Match any of the specified transaction types
    - `payment_request_id` object — UUID filter for exact matching of payment request IDs
      - `eq` string, uuid, required — Exact match for payment request ID
    - `payment_token` object — Exact string filter for payment tokens
      - `eq` string, required — Exact match for payment token
    - `customer_email` object — String contains filter for partial text matching
      - `contains` string, required — Text to search for within the field
    - `created_at` object — Date filter with range operations
      - `eq` string, date-time — Exact date match (matches entire day if time is 00:00:00)
      - `gte` string, date-time — Greater than or equal to this date
      - `lte` string, date-time — Less than or equal to this date
      - `between` string[] — Date range [start, end]
    - `currency` object — Currency filter for exact matching of ISO currency codes
      - `eq` string, required — ISO 4217 currency code
    - `order_id` object — Order ID filter for partial text matching
      - `contains` string, required — Text to search for within order ID
    - `payout_batch_id` object — UUID filter for exact matching of payment request IDs
      - `eq` string, uuid, required — Exact match for payment request ID
  - `pagination` object — Pagination parameters for transaction search
    - `page` number — Page number (1-based)
    - `limit` number — Number of items per page (max 100)
  - `sort` object[] — Sort criteria (max 2 fields for Phase 1)
    - `field` 'created_at' | 'updated_at' | 'amount' | 'converted_amount' | 'status' | 'transaction_type', required — Field to sort by
    - `direction` 'asc' | 'desc', required — Sort direction
  - `include_all_statuses` boolean — When true, includes all transaction statuses (including in-progress states like fee_paid, converted). Useful for debugging. Default: false (only shows received, completed, failed).

## Response `200`

Success

- TransactionSearchResponse — Response for transaction search with filtering, sorting, and currency totals
  - `success` boolean, required
  - `data` object[], required
    - `id` string, required
    - `transaction_number` string, required
    - `amount` number, required — Transaction amount in decimal format
    - `currency` object, required
      - `code` string, required — ISO 4217 currency code
      - `symbol` string, required — Currency symbol
      - `name` string, required — Currency name
      - `minor_unit` number, required — Number of decimal places
    - `transaction_type` 'payment' | 'refund' | 'reversal', required
    - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
    - `cross_border` boolean, required
    - `deposit_country` string, required
    - `payout_country` string, required
    - `payout_currency` object, nullable, required
      - `code` string, required — ISO 4217 currency code
      - `symbol` string, required — Currency symbol
      - `name` string, required — Currency name
      - `minor_unit` number, required — Number of decimal places
    - `exchange_rate` number, nullable, required — FX rate applied for cross-border conversion
    - `converted_amount` number, nullable, required — Amount in payout currency after FX conversion
    - `payout_at` string, date-time, nullable, required — When the payout settled
    - `payout_batch_id` string, uuid, nullable, required — ID of the payout batch this transaction belongs to
    - `test` boolean, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `settled_at` string, date-time, nullable, required
    - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
    - `problems` object[]
      - `code` string, required — Error code identifying the problem
      - `message` string, required — Human-readable description of the problem
      - `label` string, required — Display label for the problem
      - `is_resolvable` boolean, required — Whether the problem can be resolved by providing additional data
    - `target_status` union
      - 'pending'
      - 'received'
      - 'fee_paid'
      - 'converted'
      - 'completed'
      - 'failed'
      - 'cancelled'
      - 'error'
      - 'unknown'
    - `refund_status` union, required — Current refund status for payment transactions
      - 'refunding'
      - 'refunding_stuck'
      - 'refunding_failed'
      - 'partially_refunded'
      - 'fully_refunded'
    - `can_refund` boolean, required — Whether a refund can be initiated for this transaction
    - `payment_request` object, nullable, required
      - `id` string, uuid, required
      - `order_id` string, required — Merchant order ID
      - `customer` object, nullable, required
        - `name` string, required
        - `email` string, required
      - `payment_token` string, required — Payment token
    - `fees` object
      - `total` number, required — Total fees in decimal format
      - `currency` object, required
        - `code` string, required — ISO 4217 currency code
        - `symbol` string, required — Currency symbol
        - `name` string, required — Currency name
        - `minor_unit` number, required — Number of decimal places
      - `items` object[], required
        - `id` string, uuid, required
        - `amount` number, required — Fee amount in decimal format
        - `currency` object, required
          - `code` string, required — ISO 4217 currency code
          - `symbol` string, required — Currency symbol
          - `name` string, required — Currency name
          - `minor_unit` number, required — Number of decimal places
        - `fee_type` string, required
        - `rate_type` string, required
        - `rate_value` string, required
        - `rate_unit` string, required
        - `rate_base` string, required
        - `notes` string, nullable, required
        - `settlement_status` string, required
        - `invoice_id` string, uuid, nullable, required
        - `settled_at` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
    - `refunds` object[] — Refund transactions (only present for payment transactions with refunds)
      - `id` string, required
      - `transaction_number` string, required
      - `amount` number, required — Transaction amount in decimal format
      - `currency` object, required
        - `code` string, required — ISO 4217 currency code
        - `symbol` string, required — Currency symbol
        - `name` string, required — Currency name
        - `minor_unit` number, required — Number of decimal places
      - `transaction_type` 'payment' | 'refund' | 'reversal', required
      - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
      - `cross_border` boolean, required
      - `deposit_country` string, required
      - `payout_country` string, required
      - `payout_currency` object, nullable, required
        - `code` string, required — ISO 4217 currency code
        - `symbol` string, required — Currency symbol
        - `name` string, required — Currency name
        - `minor_unit` number, required — Number of decimal places
      - `exchange_rate` number, nullable, required — FX rate applied for cross-border conversion
      - `converted_amount` number, nullable, required — Amount in payout currency after FX conversion
      - `payout_at` string, date-time, nullable, required — When the payout settled
      - `payout_batch_id` string, uuid, nullable, required — ID of the payout batch this transaction belongs to
      - `test` boolean, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `settled_at` string, date-time, nullable, required
      - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
      - `problems` object[]
        - `code` string, required — Error code identifying the problem
        - `message` string, required — Human-readable description of the problem
        - `label` string, required — Display label for the problem
        - `is_resolvable` boolean, required — Whether the problem can be resolved by providing additional data
      - `target_status` union
        - 'pending'
        - 'received'
        - 'fee_paid'
        - 'converted'
        - 'completed'
        - 'failed'
        - 'cancelled'
        - 'error'
        - 'unknown'
      - `refund_status` union, required — Current refund status for payment transactions
        - 'refunding'
        - 'refunding_stuck'
        - 'refunding_failed'
        - 'partially_refunded'
        - 'fully_refunded'
      - `can_refund` boolean, required — Whether a refund can be initiated for this transaction
      - `payment_request` object, nullable, required
        - `id` string, uuid, required
        - `order_id` string, required — Merchant order ID
        - `customer` object, nullable, required
          - `name` string, required
          - `email` string, required
        - `payment_token` string, required — Payment token
      - `fees` object
        - `total` number, required — Total fees in decimal format
        - `currency` object, required
          - `code` string, required — ISO 4217 currency code
          - `symbol` string, required — Currency symbol
          - `name` string, required — Currency name
          - `minor_unit` number, required — Number of decimal places
        - `items` object[], required
          - `id` string, uuid, required
          - `amount` number, required — Fee amount in decimal format
          - `currency` object, required
            - `code` string, required — ISO 4217 currency code
            - `symbol` string, required — Currency symbol
            - `name` string, required — Currency name
            - `minor_unit` number, required — Number of decimal places
          - `fee_type` string, required
          - `rate_type` string, required
          - `rate_value` string, required
          - `rate_unit` string, required
          - `rate_base` string, required
          - `notes` string, nullable, required
          - `settlement_status` string, required
          - `invoice_id` string, uuid, nullable, required
          - `settled_at` string, date-time, nullable, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
    - `reversals` object[] — Reversal transactions (ACH returns) — only present for payment transactions with reversals
      - `id` string, required
      - `transaction_number` string, required
      - `amount` number, required — Transaction amount in decimal format
      - `currency` object, required
        - `code` string, required — ISO 4217 currency code
        - `symbol` string, required — Currency symbol
        - `name` string, required — Currency name
        - `minor_unit` number, required — Number of decimal places
      - `transaction_type` 'payment' | 'refund' | 'reversal', required
      - `status` 'pending' | 'received' | 'fee_paid' | 'converted' | 'completed' | 'failed' | 'cancelled' | 'error' | 'unknown', required
      - `cross_border` boolean, required
      - `deposit_country` string, required
      - `payout_country` string, required
      - `payout_currency` object, nullable, required
        - `code` string, required — ISO 4217 currency code
        - `symbol` string, required — Currency symbol
        - `name` string, required — Currency name
        - `minor_unit` number, required — Number of decimal places
      - `exchange_rate` number, nullable, required — FX rate applied for cross-border conversion
      - `converted_amount` number, nullable, required — Amount in payout currency after FX conversion
      - `payout_at` string, date-time, nullable, required — When the payout settled
      - `payout_batch_id` string, uuid, nullable, required — ID of the payout batch this transaction belongs to
      - `test` boolean, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `settled_at` string, date-time, nullable, required
      - `platform` 'shopify' | 'woocommerce' | 'embedded' | 'payment_link', nullable, required
      - `problems` object[]
        - `code` string, required — Error code identifying the problem
        - `message` string, required — Human-readable description of the problem
        - `label` string, required — Display label for the problem
        - `is_resolvable` boolean, required — Whether the problem can be resolved by providing additional data
      - `target_status` union
        - 'pending'
        - 'received'
        - 'fee_paid'
        - 'converted'
        - 'completed'
        - 'failed'
        - 'cancelled'
        - 'error'
        - 'unknown'
      - `refund_status` union, required — Current refund status for payment transactions
        - 'refunding'
        - 'refunding_stuck'
        - 'refunding_failed'
        - 'partially_refunded'
        - 'fully_refunded'
      - `can_refund` boolean, required — Whether a refund can be initiated for this transaction
      - `payment_request` object, nullable, required
        - `id` string, uuid, required
        - `order_id` string, required — Merchant order ID
        - `customer` object, nullable, required
          - `name` string, required
          - `email` string, required
        - `payment_token` string, required — Payment token
      - `fees` object
        - `total` number, required — Total fees in decimal format
        - `currency` object, required
          - `code` string, required — ISO 4217 currency code
          - `symbol` string, required — Currency symbol
          - `name` string, required — Currency name
          - `minor_unit` number, required — Number of decimal places
        - `items` object[], required
          - `id` string, uuid, required
          - `amount` number, required — Fee amount in decimal format
          - `currency` object, required
            - `code` string, required — ISO 4217 currency code
            - `symbol` string, required — Currency symbol
            - `name` string, required — Currency name
            - `minor_unit` number, required — Number of decimal places
          - `fee_type` string, required
          - `rate_type` string, required
          - `rate_value` string, required
          - `rate_unit` string, required
          - `rate_base` string, required
          - `notes` string, nullable, required
          - `settlement_status` string, required
          - `invoice_id` string, uuid, nullable, required
          - `settled_at` string, date-time, nullable, required
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
  - `pagination` object, required
    - `total` number, required
    - `page` number, required
    - `limit` number, required
    - `totalPages` number, required
    - `hasNextPage` boolean, required
    - `hasPreviousPage` boolean, required
  - `search_metadata` object — Metadata about the search operation
    - `filters_applied` string[], required — List of filters that were applied
    - `sort_applied` object[], required — Sort criteria that were applied
      - `field` 'created_at' | 'updated_at' | 'amount' | 'converted_amount' | 'status' | 'transaction_type', required — Field to sort by
      - `direction` 'asc' | 'desc', required — Sort direction
    - `query_execution_time` number, required — Query execution time in milliseconds
    - `total_records_scanned` number, required — Total number of records scanned
  - `totals` object[], required — Currency-based totals for filtered transactions
    - `currency` string, required — ISO 4217 currency code
    - `total_amount` number, required — Raw total amount (e.g., 2299.15)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/banqzinc/apis/quidkey-api.md) · [All operations](https://skmtc.net/banqzinc/apis/quidkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/banqzinc/quidkey-api/revisions/f86d2bdbcb08/schema)