Skip to main content

​
Overview

Use query endpoints to retrieve the latest status for a specific request. These endpoints are the main reconciliation surface for request-level state (paid/not paid, payment references, transaction hash, and optional metadata).

​
Core Endpoints

​
How It Works

1

Read a single request status

Call GET /v2/request/ to get current request-level status fields.Typical fields include:
  • hasBeenPaid
  • paymentReference
  • txHash
  • isListening
  • requestAmount — the original requested amount in invoice currency
  • detectionSource — how the payment was confirmed ("request-network" or "lifi")
  • note — additional context for non-standard settlements (e.g., LiFi fallback)
  • payerAddress — the resolved payer wallet address for the payment (null when it can’t be determined, e.g. for some contract-mediated flows)
  • payerEoaAddress — the payer’s connected wallet address (null when unavailable). It can differ from payerAddress when a smart account is used.
  • paidAmount, receivedAmount, excessAmount — the amount paid by the payer, the raw amount received by the payment route, and any route-delivered amount above what was applied to the request
  • optional metadata such as customerInfo and reference
2

Combine with events for real-time updates

Use Webhooks & Events for push updates, and use query endpoints as source-of-truth reads.
3

Use wallet-level search when needed

For wallet-level reconciliation views, use GET /v2/payments.

​
Request Status Query

GET /v2/request/{requestId} is the canonical request-level status endpoint for:
  • request payment completion checks (hasBeenPaid)
  • transaction linkage (txHash)
  • request identification (requestId, paymentReference)
  • conversion-related status fields when applicable (amountInUsd, conversionRate, conversionBreakdown)

​
Reconciliation Pattern

Webhooks First

React to events in real time and update app state immediately.

Query for Verification

Use query endpoints to confirm latest status and backfill missed events.

​
Practical Notes

  • Use requestId for deterministic lookup.
  • Keep idempotent reconciliation logic in case the same request is processed multiple times by your workers.
  • The GET /v2/request list endpoint accepts an optional walletAddress query parameter to scope results to a single payee wallet. Omit it to list across the authenticated identity’s requests.

Payment Detection

Understand automatic detection and status updates.

Query Payments

Search and reconcile payment-level events.

Webhooks & Events

Build real-time event-driven reconciliation.

​
API Reference

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