Query Payments

Overview

Use 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

How It Works

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.

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).

Read payments and pagination

The response returns:

payments array with payment and request-linked metadata
pagination.total
pagination.limit
pagination.offset
pagination.hasMore

Query Parameters

At least one search parameter is required.

Identity and Transaction Filters

string

Transaction hash (66 chars: 0x + 64 hex). Returns all payments in that transaction.

string

Wallet address (EVM 0x... or Tron T...). Returns payments where the wallet is payer or payee.

string

Payment reference hex identifier.

string

Request Network request ID.

string

Custom merchant reference string.

Type and Currency Filters

string

Payment type. Values: direct, conversion, crosschain, recurring.

string

Invoice currency (e.g., USD, EUR).

string

Payment currency ID (e.g., USDC-base, ETH-mainnet).

Date Range and Pagination

string

Start date in ISO 8601 UTC format (e.g., 2026-01-01T00:00:00.000Z).

string

End date in ISO 8601 UTC format. Must be >= fromDate.

string

Results per page.

string

Pagination offset.

Response Schema

Example response

{
  "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.

Query Requests

Read request-level status and metadata.

Payment Detection

Understand automatic detection and payment matching.

Webhooks & Events

Build real-time event-driven reconciliation.

API Reference

For full schemas and examples, see Request Network API Reference.

🔑 API Setup

⚙️ API Features

📚 API Reference

Overview

Core Endpoint

How It Works

Query Parameters

Identity and Transaction Filters

Type and Currency Filters

Response Schema

Payment fields

Practical Notes

Query Requests

Payment Detection

Webhooks & Events

API Reference

​Overview

​Core Endpoint

​How It Works

​Query Parameters

​Identity and Transaction Filters

​Type and Currency Filters

​Date Range and Pagination

​Response Schema

​Payment fields

​Practical Notes

​Related Pages

Query Requests

Payment Detection

Webhooks & Events

​API Reference

Overview

Core Endpoint

How It Works

Query Parameters

Identity and Transaction Filters

Type and Currency Filters

Date Range and Pagination

Response Schema

Payment fields

Practical Notes

Related Pages

API Reference