From 821e50487977c51c3e4388276ca5bdfeecb4067a Mon Sep 17 00:00:00 2001 From: Aimen Sahnoun Date: Mon, 2 Mar 2026 02:39:14 +0400 Subject: [PATCH] docs(api-features): rebuild reconciliation query pages with correct v2 endpoints Refactor `query-requests` and `query-payments` docs to align with actual API behavior and fix endpoint linking issues in OpenAPI references. - removed AI-generated warning banners from both pages - replaced outdated/broken API reference paths with canonical OpenAPI links - corrected endpoint linking strategy for request status and payment search routes - aligned `query-requests` to request-level reconciliation flow using: - GET /v2/request/{requestId} - GET /v2/payments (wallet-level reconciliation context) - replaced related-page bullet links with CardGroup components for consistency - rebuilt `query-payments` as endpoint-driven documentation for: - GET /v2/payments - required search parameter behavior - filter groups (identity/tx, type/currency, date/pagination) - response pagination fields (`total`, `limit`, `offset`, `hasMore`) - practical reconciliation notes (AND semantics, batch tx behavior, idempotency) - removed legacy-domain dependencies and invalid internal endpoint links - kept structure consistent with other migrated API Features pages --- api-features/query-payments.mdx | 142 +++++++++++++++++++------------- 1 file changed, 84 insertions(+), 58 deletions(-) diff --git a/api-features/query-payments.mdx b/api-features/query-payments.mdx index b13e5f3..a6584e9 100644 --- a/api-features/query-payments.mdx +++ b/api-features/query-payments.mdx @@ -3,88 +3,114 @@ title: "Query Payments" description: "Advanced payment search and filtering with the GET /payments endpoint" --- - -**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions). - - ## Overview -The GET /payments endpoint provides comprehensive payment search and filtering capabilities, enabling detailed payment history analysis and transaction monitoring. +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. -## Endpoint Features +This endpoint is designed for wallet-level reconciliation, payment history search, and operational reporting. - - - Multiple search criteria - - - - Large dataset management - - +## Core Endpoint + +- [GET /v2/payments](https://api.request.network/open-api/#tag/v2payments/GET/v2/payments) ## How It Works -```mermaid -graph LR - A[Query Parameters] --> B[Filter Payments] - B --> C[Sort Results] - C --> D[Paginate Response] - D --> E[Return Data] -``` + + +`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` -**Search Process:** -1. **Filter:** Apply search criteria -2. **Sort:** Order by date, amount, or status -3. **Paginate:** Handle large result sets -4. **Return:** Structured payment data +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 -### Basic Filters -- **Date Range:** Start and end dates -- **Amount Range:** Minimum and maximum amounts -- **Currency:** Specific token or fiat currency -- **Status:** Payment completion state +### 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 -### Advanced Filters -- **Payer Address:** Filter by payment sender -- **Payee Address:** Filter by payment recipient -- **Transaction Hash:** Specific transaction lookup -- **Request ID:** Payments for specific requests +### Type and Currency Filters +- `type`: `direct`, `conversion`, `crosschain`, `recurring` +- `invoiceCurrency` +- `paymentCurrency` -## Network Filtering +### Time and Pagination +- `fromDate`, `toDate` +- `limit`, `offset` - - Payments on specific blockchain + + Combine request, wallet, currency, and date filters for targeted reconciliation queries. - - Crosschain payment search + + Use `limit`/`offset` and `hasMore` to process large result sets safely. -### Supported Networks -Filter payments across Ethereum, Polygon, Arbitrum, BSC, and other supported networks. - ## Response Data -### Payment Information -- **Basic Details:** Amount, currency, timestamp -- **Network Data:** Blockchain, transaction hash, block number -- **Participants:** Payer and payee addresses -- **Status:** Confirmation state and payment completion +Common fields include payment-level data and linked request metadata: -### Enhanced Data -- **Fee Breakdowns:** Detailed fee structure with USD amounts -- **Exchange Rates:** Historical conversion rates -- **Gas Costs:** Transaction fee information +- 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`) -## Pagination +## Practical Notes -Handle large datasets with cursor-based pagination for optimal performance. +- 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. + + -## Implementation Details +## API Reference -See [API Reference - GET /payments](/api-reference/endpoints/get-payments) for complete technical documentation. \ No newline at end of file +For full schemas and examples, see [Request Network API Reference](https://api.request.network/open-api).