Payment links, received payments & refunds

Payment links let the agent get paid. Create a link, share its URL, and payers (people or other agents) pay it in USDC. Payments go to the linked wallet.

All amounts here are USDC atomic units (6 decimals): 1000000 = 1.00 USDC.

paymentlink-create

fluxa-wallet paymentlink-create --amount 5000000 --desc "AI Research Report" \
  --max-uses 100 --expires "2026-12-31T00:00:00.000Z"

Flag	Type	Required	Default	Description
--amount	integer, atomic units	Yes	—	Price per payment
--desc	string	No	—	Description shown to payers
--resource	string	No	—	Content delivered to the payer after payment
--expires	ISO 8601 date-time	No	never	When the link stops accepting payments
--max-uses	integer	No	unlimited	Maximum number of payments
--network	string	No	base	Network

{
  "success": true,
  "data": {
    "paymentLink": {
      "linkId": "lnk_a1b2c3d4e5",
      "amount": "5000000",
      "currency": "USDC",
      "network": "base",
      "description": "AI Research Report",
      "status": "active",
      "expiresAt": "2026-12-31T00:00:00.000Z",
      "maxUses": 100,
      "useCount": 0,
      "url": "https://wallet.fluxapay.xyz/pay/lnk_a1b2c3d4e5"
    }
  }
}

Share data.paymentLink.url with payers.

Error	What to do
Missing required parameter: --amount	Supply --amount
Amount must be a positive integer (smallest units)	Convert to atomic units. No decimals

paymentlink-list

fluxa-wallet paymentlink-list --limit 10

Flag	Type	Required	Description
--limit	integer	No	Maximum number of links returned

Returns data.paymentLinks, an array of link objects shaped like the one above.

paymentlink-get

fluxa-wallet paymentlink-get --id lnk_a1b2c3d4e5

Flag	Type	Required	Description
--id	string	Yes	Link ID (lnk_…)

Returns data.paymentLink.

paymentlink-update

fluxa-wallet paymentlink-update --id lnk_a1b2c3d4e5 --status disabled
fluxa-wallet paymentlink-update --id lnk_a1b2c3d4e5 --expires null --max-uses null

Flag	Type	Required	Description
--id	string	Yes	Link ID
--desc	string	No	New description
--resource	string	No	New delivered content
--status	active | disabled	No	Turn the link on or off
--expires	ISO 8601, or null	No	New expiry. null removes it
--max-uses	integer, or null	No	New usage cap. null removes it

Only the fields you pass are changed.

paymentlink-delete

fluxa-wallet paymentlink-delete --id lnk_a1b2c3d4e5

Flag	Type	Required	Description
--id	string	Yes	Link ID

To stop payments but keep the link and its history, use paymentlink-update --status disabled instead.

paymentlink-payments

Lists payments made on one link.

fluxa-wallet paymentlink-payments --id lnk_a1b2c3d4e5 --limit 10

Flag	Type	Required	Description
--id	string	Yes	Link ID
--limit	integer	No	Maximum number of records

{
  "success": true,
  "data": {
    "payments": [
      {
        "id": 49217,
        "payerAddress": "0xPayer...",
        "amount": "5000000",
        "currency": "USDC",
        "settlementStatus": "settled",
        "settlementTxHash": "0xabc...",
        "createdAt": "2026-10-27T10:30:00.000Z"
      }
    ]
  }
}

A payment has completed when settlementStatus is settled. failed means it failed. Treat any other value as processing.

received-records

Lists every payment the agent has received, across all its payment links.

fluxa-wallet received-records --limit 20 --offset 0

Flag	Type	Required	Default	Description
--limit	integer, max 100	No	20	Page size
--offset	integer	No	0	Pagination offset

Returns data.payments. Each record has the fields shown above, plus sourceType, description, paymentLinkId and payerEmail where available.

received-record

fluxa-wallet received-record --id 49217

Flag	Type	Required	Description
--id	integer	Yes	Numeric payment record ID from received-records or paymentlink-payments

Returns data.payment. It has the same fields as the list, plus network and payTo.

Error	What to do
Invalid payment ID: must be a number	Use the numeric id, not the link ID

Refunds

A refund returns all or part of a received payment to the payer. Like a payout, it needs the user's approval: the CLI returns a refundUrl for the user to approve. If nobody approves it within about 24 hours, the refund expires.

paymentlink-refund-create

# Full refund
fluxa-wallet paymentlink-refund-create --payment-id 49217

# Partial refund with a reason
fluxa-wallet paymentlink-refund-create --payment-id 49217 --amount 500000 --reason "Partial refund"

Flag	Type	Required	Default	Description
--payment-id	integer	Yes	—	Numeric payment record ID
--amount	integer, atomic units	No	full amount	Partial refund amount
--reason	string	No	—	Stored with the refund

{
  "success": true,
  "data": {
    "refundId": "plr_xxxxxxxxxxxx",
    "refundUrl": "https://walletapi.fluxapay.xyz/refundlink/plr_xxxxxxxxxxxx",
    "paymentId": 49217,
    "amount": "500000",
    "currency": "USDC",
    "refundType": "partial",
    "status": "pending",
    "expiresAt": "2026-10-28T10:30:00.000Z"
  }
}

Send the user the complete refundUrl. refundId is a string (plr_…). Pass it unchanged to the commands below.

Error	What to do
Missing required parameter: --payment-id	Supply the numeric payment record ID
Invalid payment ID: must be a number	Use the numeric id from received-records
Amount must be a positive integer (atomic units)	Convert to atomic units

Refund status

Outcome	status
Awaiting approval	pending
Completed	settled (refundTxHash is set)
Failed / not sent	failed, expired, cancelled

Treat any other value as processing. A completed refund is on-chain and can't be reversed.

paymentlink-refund-list

fluxa-wallet paymentlink-refund-list --limit 20 --offset 0

Flag	Type	Required	Default	Description
--limit	integer, max 100	No	20	Page size
--offset	integer	No	0	Pagination offset

Returns data.refunds.

paymentlink-refund-get

fluxa-wallet paymentlink-refund-get --id plr_xxxxxxxxxxxx

Flag	Type	Required	Description
--id	string	Yes	Refund ID (plr_…)

paymentlink-refund-cancel

Cancels a refund that's still awaiting approval. A completed refund can't be cancelled.

fluxa-wallet paymentlink-refund-cancel --id plr_xxxxxxxxxxxx

Flag	Type	Required	Description
--id	string	Yes	Refund ID (plr_…)

See also: Payment Link guide.