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

# Query Payments

> Advanced payment search and filtering with the GET /v2/payments endpoint

## Overview

Use [GET /v2/payments](https://api.request.network/open-api/#tag/v2payments/GET/v2/payments) to search payments with filters such as transaction hash, wallet, request identifiers, currency, type, and date range.

This endpoint is designed for wallet-level reconciliation, payment history search, and operational reporting.

## Core Endpoint

* [GET /v2/payments](https://api.request.network/open-api/#tag/v2payments/GET/v2/payments)

## How It Works

<Steps>
  <Step title="Provide at least one search parameter">
    `GET /v2/payments` requires at least one of these filters:

    * `txHash`
    * `walletAddress`
    * `paymentReference`
    * `requestId`
    * `reference`
    * `type`
    * `invoiceCurrency`
    * `paymentCurrency`

    If none are provided, validation fails.
  </Step>

  <Step title="Add optional filters for precision">
    Optional filters include:

    * `fromDate`, `toDate` (ISO 8601 UTC)
    * `limit`, `offset`

    Date ranges are validated (`toDate` must be after or equal to `fromDate`).
  </Step>

  <Step title="Read payments and pagination">
    The response returns:

    * `payments` array with payment and request-linked metadata
    * `pagination.total`
    * `pagination.limit`
    * `pagination.offset`
    * `pagination.hasMore`
  </Step>
</Steps>

## Query Parameters

At least one search parameter is required.

### Identity and Transaction Filters

<ParamField query="txHash" type="string">
  Transaction hash (66 chars: `0x` + 64 hex). Returns all payments in that transaction.
</ParamField>

<ParamField query="walletAddress" type="string">
  Wallet address (EVM `0x...` or Tron `T...`). Returns payments where the wallet is payer or payee.
</ParamField>

<ParamField query="paymentReference" type="string">
  Payment reference hex identifier.
</ParamField>

<ParamField query="requestId" type="string">
  Request Network request ID.
</ParamField>

<ParamField query="reference" type="string">
  Custom merchant reference string.
</ParamField>

### Type and Currency Filters

<ParamField query="type" type="string">
  Payment type. Values: `direct`, `conversion`, `crosschain`, `recurring`.
</ParamField>

<ParamField query="invoiceCurrency" type="string">
  Invoice currency (e.g., `USD`, `EUR`).
</ParamField>

<ParamField query="paymentCurrency" type="string">
  Payment currency ID (e.g., `USDC-base`, `ETH-mainnet`).
</ParamField>

### Date Range and Pagination

<ParamField query="fromDate" type="string">
  Start date in ISO 8601 UTC format (e.g., `2026-01-01T00:00:00.000Z`).
</ParamField>

<ParamField query="toDate" type="string">
  End date in ISO 8601 UTC format. Must be >= `fromDate`.
</ParamField>

<ParamField query="limit" type="string">
  Results per page.
</ParamField>

<ParamField query="offset" type="string">
  Pagination offset.
</ParamField>

## Response Schema

```json Example response theme={null}
{
  "payments": [
    {
      "id": "01HXAMPLE1234567890ABCDEF",
      "amount": "100.00",
      "sourceNetwork": "base",
      "destinationNetwork": "base",
      "sourceTxHash": "0x1234...abcdef",
      "destinationTxHash": null,
      "timestamp": "2026-01-15T10:30:00.000Z",
      "type": "direct",
      "currency": "USD",
      "paymentCurrency": "USDC",
      "detectionSource": "request-network",
      "note": null,
      "fees": [
        {
          "type": "gas",
          "stage": "sending",
          "amount": "0.002",
          "amountInUSD": "0.005",
          "currency": "ETH",
          "provider": "request-network"
        }
      ],
      "request": {
        "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
        "paymentReference": "0xb3581f0b0f74cc61",
        "hasBeenPaid": true,
        "customerInfo": null,
        "reference": "ORDER-2024-001234"
      }
    }
  ],
  "pagination": {
    "total": 157,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}
```

### Payment fields

| Field                | Type           | Description                                                                           |
| -------------------- | -------------- | ------------------------------------------------------------------------------------- |
| `id`                 | string         | Unique payment identifier                                                             |
| `amount`             | string         | Human-readable payment amount                                                         |
| `sourceNetwork`      | string         | Originating blockchain network                                                        |
| `destinationNetwork` | string         | Receiving blockchain network                                                          |
| `sourceTxHash`       | string \| null | Source chain transaction hash                                                         |
| `destinationTxHash`  | string \| null | Destination chain tx hash (crosschain)                                                |
| `timestamp`          | string         | ISO 8601 timestamp                                                                    |
| `type`               | string         | `direct`, `conversion`, `crosschain`, `recurring`                                     |
| `currency`           | string         | Invoice currency                                                                      |
| `paymentCurrency`    | string         | Payment currency                                                                      |
| `fees`               | array          | Fee breakdown with type, amount, currency, provider                                   |
| `detectionSource`    | string \| null | How the payment was confirmed: `"request-network"` or `"lifi"`                        |
| `note`               | string \| null | Additional context for non-standard settlements (e.g., LiFi fallback)                 |
| `recurringPaymentId` | string \| null | Recurring payment ID if applicable                                                    |
| `request`            | object         | Linked request with requestId, paymentReference, hasBeenPaid, customerInfo, reference |

## Practical Notes

* Search parameters are combined with AND semantics.
* Searching by `txHash` or `walletAddress` can return multiple rows from batch transactions.
* Keep your reconciliation workers idempotent in case the same payment appears across repeated queries.

## Related Pages

<CardGroup cols={3}>
  <Card title="Query Requests" href="/api-features/query-requests">
    Read request-level status and metadata.
  </Card>

  <Card title="Payment Detection" href="/api-features/payment-detection">
    Understand automatic detection and payment matching.
  </Card>

  <Card title="Webhooks & Events" href="/api-features/webhooks-events">
    Build real-time event-driven reconciliation.
  </Card>
</CardGroup>

## API Reference

For full schemas and examples, see [Request Network API Reference](https://api.request.network/open-api).