Payment Links

Create and manage payment collection links — shareable URLs that let anyone pay a fixed amount to the agent's wallet.

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

---

Create payment link

curl -X POST https://walletapi.fluxapay.xyz/api/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "amount": "1000000",
    "currency": "USDC",
    "network": "base",
    "description": "Premium API Access — 1 USDC",
    "resourceContent": "{\"apiKey\": \"sk_live_xxx\", \"message\": \"Thank you!\"}",
    "expiresAt": "2025-12-31T23:59:59Z",
    "maxUses": 100
  }'

Key fields:

Field	Type	Required	Description
amount	string	Yes	Price in atomic units (1000000 = 1.0 USDC)
currency	string	No	Currency, defaults to USDC
network	string	No	base (default) or base-sepolia
description	string	No	Human-readable label shown to the payer
resourceContent	string	No	JSON or text delivered to the payer after payment
expiresAt	string	No	ISO 8601 expiry timestamp
maxUses	number	No	Max payments accepted; null for unlimited

Response (201):

{
  "success": true,
  "paymentLink": {
    "id": 1,
    "linkId": "pl_abc123xyz456",
    "amount": "1000000",
    "currency": "USDC",
    "network": "base",
    "payTo": "0xYourWalletAddress",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "scheme": "exact",
    "description": "Premium API Access — 1 USDC",
    "resourceContent": "{\"apiKey\": \"sk_live_xxx\", \"message\": \"Thank you!\"}",
    "status": "active",
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "maxUses": 100,
    "useCount": 0,
    "url": "https://walletapi.fluxapay.xyz/paymentlink/pl_abc123xyz456",
    "createdAt": "2025-01-25T12:00:00.000Z",
    "updatedAt": "2025-01-25T12:00:00.000Z"
  }
}

Share the url with payers.

---

List payment links

curl https://walletapi.fluxapay.xyz/api/payment-links?limit=50 \
  -H "Authorization: Bearer $JWT_TOKEN"

Query parameters:

Param	Type	Default	Description
limit	number	100	Max results (max 500)

Response (200):

{
  "paymentLinks": [ /* same shape as create response */ ]
}

---

Get payment link

curl https://walletapi.fluxapay.xyz/api/payment-links/pl_abc123xyz456 \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (200):

{
  "paymentLink": { /* same shape as create response */ }
}

---

Update payment link

curl -X PATCH https://walletapi.fluxapay.xyz/api/payment-links/pl_abc123xyz456 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "description": "Updated description",
    "status": "disabled",
    "maxUses": 200
  }'

Updatable fields:

Field	Type	Description
description	string	Update description
resourceContent	string	Update delivered content
status	string	active or disabled
expiresAt	string	ISO 8601 timestamp, or null to remove expiry
maxUses	number	Max uses, or null to remove limit

Response (200):

{
  "success": true,
  "paymentLink": { /* updated link */ }
}

---

Delete payment link

Soft-deletes a payment link.

curl -X DELETE https://walletapi.fluxapay.xyz/api/payment-links/pl_abc123xyz456 \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (200):

{
  "success": true,
  "message": "Payment link deleted"
}

---

Get payments for a link

List all payments received through a specific payment link.

curl https://walletapi.fluxapay.xyz/api/payment-links/pl_abc123xyz456/payments \
  -H "Authorization: Bearer $JWT_TOKEN"

Query parameters:

Param	Type	Default	Description
limit	number	100	Max results (max 500)

Response (200):

{
  "payments": [
    {
      "id": 1,
      "payerAddress": "0xPayerWalletAddress",
      "amount": "1000000",
      "currency": "USDC",
      "settlementStatus": "settled",
      "settlementTxHash": "0xabc123...",
      "createdAt": "2025-01-25T13:00:00.000Z"
    }
  ]
}

---

Public payment endpoint (x402)

This is a public endpoint — no authentication required. Clients access this URL to make payments.

Step 1 — Request payment requirements

curl -i https://walletapi.fluxapay.xyz/paymentlink/pl_abc123xyz456

Response (402 Payment Required):

{
  "error": "Payment Required",
  "x402Version": 2,
  "accepts": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "1000000",
      "resource": "/paymentlink/pl_abc123xyz456",
      "description": "Premium API Access — 1 USDC",
      "payTo": "0xRecipientAddress",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

Step 2 — Submit payment

Sign an EIP-3009 TransferWithAuthorization, encode the payload as Base64, and attach it as the X-Payment header.

curl -i https://walletapi.fluxapay.xyz/paymentlink/pl_abc123xyz456 \
  -H "X-Payment: eyJ4NDAyVmVyc2lvbiI6MiwicGF5bG9hZCI6ey..."

Response (200 — success):

{
  "status": "success",
  "resource": "{\"apiKey\": \"sk_live_xxx\", \"message\": \"Thank you!\"}",
  "receipt": {
    "txHash": "0xabc123def456...",
    "payer": "0xPayerAddress",
    "amount": "1000000",
    "currency": "USDC"
  }
}

Response (402 — failed):

{
  "error": "Payment failed",
  "reason": "Invalid signature"
}