Received Payments

Query all payments received across Payment Links and Unify Payment Links (UPL) in a single unified view.

All endpoints require Authorization: Bearer <agent-jwt>.

---

List received payments

List all payments received by the current user, from both Payment Links and UPL.

curl https://walletapi.fluxapay.xyz/api/received-payments?limit=20&offset=0 \
  -H "Authorization: Bearer $JWT_TOKEN"

Query parameters

Param	Type	Default	Description
limit	number	20	Max results (max 100)
offset	number	0	Pagination offset

Filter parameters

Use filters to locate specific payments — useful before initiating a refund.

Param	Type	Description
payerAddress	string	Filter by payer wallet address
sourceType	string	payment_link or unify_payment_link
agentId	number	Filter by Agent ID
txHash	string	Exact match on settlement tx hash
minAmount	string	Minimum amount (atomic units)
maxAmount	string	Maximum amount (atomic units)
startDate	string	Start time (ISO 8601)
endDate	string	End time (ISO 8601)

Filter examples

# Find all UPL payments from a specific payer
curl "https://walletapi.fluxapay.xyz/api/received-payments?payerAddress=0xAAA...&sourceType=unify_payment_link" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Look up by transaction hash
curl "https://walletapi.fluxapay.xyz/api/received-payments?txHash=0xTX222..." \
  -H "Authorization: Bearer $JWT_TOKEN"

# Filter by date range and minimum amount
curl "https://walletapi.fluxapay.xyz/api/received-payments?startDate=2026-04-01&endDate=2026-04-13&minAmount=1000000" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (200)

{
  "payments": [
    {
      "id": 1,
      "payerAddress": "0xPayerWalletAddress",
      "amount": "1000000",
      "currency": "USDC",
      "settlementStatus": "settled",
      "settlementTxHash": "0xabc123...",
      "sourceType": "payment_link",
      "description": "Premium API Access — 1 USDC",
      "paymentLinkId": "pl_abc123xyz456",
      "payerEmail": "payer@example.com",
      "createdAt": "2026-03-24T13:00:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
id	number	Payment record ID
payerAddress	string	Payer's wallet address
amount	string	Amount in atomic units (1000000 = 1.0 USDC)
currency	string	Currency type
settlementStatus	string	settled, pending, or failed
settlementTxHash	string | null	Onchain transaction hash
sourceType	string	payment_link or unify_payment_link
description	string | null	Description (from payment or link)
paymentLinkId	string | null	Associated Payment Link ID (pl_*); null for UPL
payerEmail	string | null	Payer's email (resolved via wallet address); null for external payers
createdAt	string	Payment timestamp (ISO 8601)

---

Get received payment detail

Get details for a single received payment.

curl https://walletapi.fluxapay.xyz/api/received-payments/1 \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (200)

{
  "payment": {
    "id": 1,
    "payerAddress": "0xPayerWalletAddress",
    "amount": "1000000",
    "currency": "USDC",
    "settlementStatus": "settled",
    "settlementTxHash": "0xabc123...",
    "sourceType": "payment_link",
    "description": "Premium API Access — 1 USDC",
    "paymentLinkId": "pl_abc123xyz456",
    "payerEmail": "payer@example.com",
    "network": "base",
    "payTo": "0xRecipientAddress",
    "createdAt": "2026-03-24T13:00:00.000Z"
  }
}

Additional fields compared to the list endpoint:

Field	Type	Description
network	string | null	Network: base, base-sepolia
payTo	string | null	Recipient wallet address

Error responses

Status	Description
400	Invalid payment ID
404	Payment record not found or not authorized to view