Linked cards (Beta)

Beta

Linked cards are in beta and only available to some wallets. If the wallet owner doesn't have access, these endpoints return 404 with code: "NOT_FOUND". The response shapes may change.

These are read-only endpoints. They let an agent see which payment cards the wallet owner has linked, and which card mandates (CARD_USD, see Mandates) the agent holds on each card.

Both endpoints require Authorization: Bearer <agent-jwt>. Responses use this format:

{ "success": true, "data": { ... } }
{ "success": false, "error": { "code": "...", "message": "..." } }

---

List linked cards

GET/api/vic/agent/cardsBearer agent-jwt↗

curl "https://walletapi.fluxapay.xyz/api/vic/agent/cards?limit=20" \
  -H "Authorization: Bearer $JWT_TOKEN"

Param	Description
limit	Page size, 1–100.
cursor	nextCursor from the previous page.

Any other query parameter returns 400 invalid_request.

{
  "success": true,
  "data": {
    "cards": [
      { "id": "3f6c2b1e-8d4a-4c7e-9b2f-1a2b3c4d5e6f", "status": "ACTIVE", "brand": "visa", "last4": "4242", "expMonth": 12, "expYear": 2028 }
    ],
    "nextCursor": null
  }
}

---

List the agent's mandates on a card

GET/api/vic/agent/cards/:cardId/mandatesBearer agent-jwt↗

curl https://walletapi.fluxapay.xyz/api/vic/agent/cards/3f6c2b1e-8d4a-4c7e-9b2f-1a2b3c4d5e6f/mandates \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "success": true,
  "data": {
    "cardId": "3f6c2b1e-8d4a-4c7e-9b2f-1a2b3c4d5e6f",
    "mandates": [
      {
        "mandateId": "mand_Q2h8x0b1Yc3k9ZpLmN4rTw",
        "status": "signed",
        "currency": "CARD_USD",
        "decimals": 2,
        "limitAmount": "12000",
        "spentAmount": "0",
        "pendingSpentAmount": "0",
        "remainingAmount": "12000",
        "isEnabled": true,
        "naturalLanguage": "Buy one pair of running shoes, up to $120",
        "purpose": "Buy one pair of running shoes, up to $120",
        "sourceCardId": "3f6c2b1e-8d4a-4c7e-9b2f-1a2b3c4d5e6f",
        "cardActivatedAt": null,
        "validFrom": "2026-10-27T10:00:00.000Z",
        "validUntil": "2026-10-27T11:00:00.000Z",
        "signedAt": "2026-10-27T10:02:00.000Z",
        "createdAt": "2026-10-27T10:00:00.000Z",
        "approvalUrl": null
      }
    ]
  }
}

Amounts are in cents (decimals: 2).

status	Meaning
pending_signature	Awaiting the user's signature. Show approvalUrl.
signed	Approved and usable.
disabled	The user turned it off.
not_yet_valid	Approved, but its validity window hasn't started yet.
expired	Past validUntil.
any other value	Treat as processing (if recently signed) or not usable.

Errors

HTTP	error.code	Meaning
400	invalid_request / invalid_card_id / invalid_card_list_limit / invalid_card_list_cursor	Invalid query parameter or card ID (card IDs are UUIDs).
401	agent_auth_failed / wrong_token_type	Invalid agent JWT, or a VC was sent.
403	agent_not_authorized	The agent isn't linked to an authorized wallet.
404	NOT_FOUND	Linked cards aren't available for this wallet.
5xx	–	The card service is temporarily unavailable. Retry later. The response includes retryable.