Query Payments

Advanced payment search and filtering with the GET /payments endpoint

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

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

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

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

txHash · string

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

walletAddress · string

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

paymentReference · string

Payment reference hex identifier.

requestId · string

Request Network request ID.

reference · string

Custom merchant reference string.

Type and Currency Filters

type · string

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

invoiceCurrency · string

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

paymentCurrency · string

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

Date Range and Pagination

fromDate · string

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

toDate · string

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

limit · string

Results per page.

offset · 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",
      "fees": [
        {
          "type": "gas",
          "stage": "sending",
          "amount": "0.002",
          "amountInUSD": "0.005",
          "currency": "ETH",
          "provider": "request-network"
        }
      ],
      "request": {
        "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
        "paymentReference": "0xb3581f0b0f74cc61",
        "hasBeenPaid": true,
        "customerInfo": {
          "firstName": "John",
          "lastName": "Doe",
          "email": "[e-mail]"
        },
        "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
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

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.