Skip to content

query-payments.mdx

Latest commit

 

History

History
116 lines (85 loc) · 3.28 KB

query-payments.mdx

File metadata and controls

116 lines (85 loc) · 3.28 KB
title Query Payments
description 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

How It Works

`GET /v2/payments` requires at least one of these filters:
  • txHash
  • walletAddress
  • paymentReference
  • requestId
  • reference
  • type
  • invoiceCurrency
  • paymentCurrency

If none are provided, validation fails.

Optional filters include:
  • fromDate, toDate (ISO 8601 UTC)
  • limit, offset

Date ranges are validated (toDate must be after or equal to fromDate).

The response returns:
  • payments array with payment and request-linked metadata
  • pagination.total
  • pagination.limit
  • pagination.offset
  • pagination.hasMore

Filter Options

Identity and Transaction Filters

  • txHash: find payments by blockchain transaction hash
  • walletAddress: find payments where wallet is payer or payee
  • paymentReference: search by payment reference
  • requestId: search by specific request ID
  • reference: search by merchant reference

Type and Currency Filters

  • type: direct, conversion, crosschain, recurring
  • invoiceCurrency
  • paymentCurrency

Time and Pagination

  • fromDate, toDate
  • limit, offset
Combine request, wallet, currency, and date filters for targeted reconciliation queries. Use `limit`/`offset` and `hasMore` to process large result sets safely.

Response Data

Common fields include payment-level data and linked request metadata:

  • payment identifiers and transaction hashes
  • source/destination network and amounts
  • payment type and currency fields
  • fee objects
  • linked request information (requestId, paymentReference, hasBeenPaid, optional 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

Read request-level status and metadata. Understand automatic detection and payment matching. Build real-time event-driven reconciliation.

API Reference

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