---
title: "List payments"
method: GET
path: "/v1/payments"
tags: ["Payments"]
---

# List payments

`GET /v1/payments`

Retrieve paginated payments with optional filters.

## Query parameters

- `startTs` string, date-time
- `endTs` string, date-time
- `token_symbol` string[]
- `asset` string
- `network` string
- `sortBy` 'date' | 'amount'
- `sortDir` 'asc' | 'desc'
- `cursor` string
- `limit` integer
- `status` string[]
- `referenceId` string
- `merchantId` string[]

## Headers

- `WCP-Version` string

## Response `200`

Payments with statistics

- MerchantPaymentsResponse
  - `data` object[], required
    - `paymentId` string, required — Unique payment identifier
    - `merchant` object, required
      - `id` string, required — Partner-provided merchant ID
      - `name` string — Merchant display name
      - `iconUrl` string, nullable — Merchant logo URL
    - `referenceId` string, required — Idempotency / reference ID provided at payment creation
    - `status` 'requires_action' | 'processing' | 'succeeded' | 'failed' | 'expired', required
    - `isTerminal` boolean, required — Whether the payment has reached a final state
    - `fiatAmount` MerchantPaymentFiatAmount — Fiat-denominated amount
      - `unit` string, required — Fiat unit, for example "iso4217/USD"
      - `value` string, required — Amount in minor units for the fiat currency
      - `display` object, required — Display metadata for fiat-denominated amounts
        - `assetSymbol` string, required
        - `assetName` string, required
        - `decimals` integer, required
    - `tokenAmount` MerchantPaymentTokenAmount — Token-denominated amount
      - `unit` string, required — Token unit, for example "caip19/..."
      - `value` string, required — Amount in minor units for the token asset
      - `display` object, nullable, required — Display metadata for token-denominated amounts
        - `assetSymbol` string, required
        - `assetName` string, required
        - `decimals` integer, required
        - `iconUrl` string
        - `networkName` string
        - `networkIconUrl` string
    - `buyer` object — Buyer wallet information
      - `accountCaip10` string, required — Buyer address as a [CAIP-10](https://standards.chainagnostic.org/CAIPs/caip-10) account ID
      - `accountProviderName` string — Wallet provider name
      - `accountProviderIcon` string — Wallet provider logo URL
    - `transaction` object — On-chain transaction details
      - `networkId` string, required — Numeric chain ID
      - `hash` string — On-chain transaction hash
      - `nonce` integer — Transaction nonce
    - `fees` object — Fee breakdown derived from payment option data. Omitted when total fee data is unavailable.
      - `total` union, required — Total fee amount.
        - MerchantPaymentFiatAmount — Fiat-denominated amount
          - `unit` string, required — Fiat unit, for example "iso4217/USD"
          - `value` string, required — Amount in minor units for the fiat currency
          - `display` object, required — Display metadata for fiat-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
        - MerchantPaymentTokenAmount — Token-denominated amount
          - `unit` string, required — Token unit, for example "caip19/..."
          - `value` string, required — Amount in minor units for the token asset
          - `display` object, nullable, required — Display metadata for token-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
            - `iconUrl` string
            - `networkName` string
            - `networkIconUrl` string
      - `fixed` union — Fixed fee component.
        - MerchantPaymentFiatAmount — Fiat-denominated amount
          - `unit` string, required — Fiat unit, for example "iso4217/USD"
          - `value` string, required — Amount in minor units for the fiat currency
          - `display` object, required — Display metadata for fiat-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
        - MerchantPaymentTokenAmount — Token-denominated amount
          - `unit` string, required — Token unit, for example "caip19/..."
          - `value` string, required — Amount in minor units for the token asset
          - `display` object, nullable, required — Display metadata for token-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
            - `iconUrl` string
            - `networkName` string
            - `networkIconUrl` string
      - `percentage` string — Percentage fee component as a decimal percentage string, not a ratio. For example, "0.4" means 0.4%.
    - `settlement` MerchantPaymentSettlement — Settlement details. Omitted when settlement details cannot be reported yet. When present, `settled` is always included. When `settled` is `false`, no additional settlement fields are returned. When `settled` is `true`, `amount` and `txHash` are always included.
      - `settled` boolean, required — Whether settlement is complete.
      - `amount` union — Net settlement amount after fees in the settlement unit. Present only when `settled` is `true`.
        - MerchantPaymentFiatAmount — Fiat-denominated amount
          - `unit` string, required — Fiat unit, for example "iso4217/USD"
          - `value` string, required — Amount in minor units for the fiat currency
          - `display` object, required — Display metadata for fiat-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
        - MerchantPaymentTokenAmount — Token-denominated amount
          - `unit` string, required — Token unit, for example "caip19/..."
          - `value` string, required — Amount in minor units for the token asset
          - `display` object, nullable, required — Display metadata for token-denominated amounts
            - `assetSymbol` string, required
            - `assetName` string, required
            - `decimals` integer, required
            - `iconUrl` string
            - `networkName` string
            - `networkIconUrl` string
      - `txHash` string — Settlement transaction hash. Present only when `settled` is `true`.
    - `createdAt` string, required — ISO 8601 timestamp
    - `lastUpdatedAt` string, required — ISO 8601 timestamp
    - `settledAt` string — ISO 8601 timestamp, present only when `settlement.settled` is `true`
  - `nextCursor` string, nullable, required — Cursor for the next page, or null if no more results
  - `stats` object, required — Aggregate statistics for the query
    - `totalRevenue` object[], required
      - `amount` number, required — Revenue amount in currency's standard unit
      - `currency` string, required — ISO 4217 currency code
    - `totalTransactions` integer, required — Total payments matching the query
    - `totalCustomers` integer, required — Unique buyers matching the query

## Other responses

- `400` — Bad request — invalid parameters or API version
- `401` — Unauthorized — missing or invalid partner API key
- `500` — Internal server error
- `502` — Bad gateway — upstream service returned an error

---

[API](https://skmtc.net/walletconnect/apis/walletconnect-pay-api.md) · [All operations](https://skmtc.net/walletconnect/apis/walletconnect-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/walletconnect/walletconnect-pay-api/versions/8e5708191dde/schema)