Linked card Beta

With a linked card, an agent pays a merchant checkout with a card the user has linked in the FluxA Wallet. The agent never sees the real card number. Each purchase uses a CARD_USD mandate that is limited to one merchant and a maximum amount, and the user approves it on one of their linked cards.

Availability

Linked cards are enabled per account. If they aren't available, commands return Linked cards are not available for this wallet. The user can check the Agent Cards page in the wallet.

For cards funded from the wallet balance, see Agent cards instead.

Flow

# 1. Does the user have a linked card?
fluxa-wallet linked-card list

# 2. Is there already a mandate that can pay this merchant and amount (cents)?
fluxa-wallet linked-card mandates --host www.amazon.com --amount 3000

# 3. If not, create one ($30.00 at Amazon) and send the user the approvalUrl
fluxa-wallet mandate-create --currency CARD_USD --desc "Buy a USB-C cable on Amazon, up to $30" \
  --amount 3000 --merchant-name Amazon --merchant-url https://www.amazon.com --merchant-country US

# 4. Wait until it's ready
fluxa-wallet linked-card subcard --mandate mand_xxx      # repeat until "isReady": true

# 5. Pay the merchant checkout
fluxa-wallet headless-checkout --mandate mand_xxx --attempt wpa_xxx --billing @billing.json

Confirm the merchant, product and amount with the user before steps 3 and 5. Never ask the user for card numbers: cards are linked only in the wallet.

mandate-create --currency CARD_USD

Flag	Required	Description
--desc	Yes	What is being bought. Shown to the user. Max 255 bytes, single line
--amount	Yes	Maximum amount in US cents (3000 = $30.00)
--merchant-name	Yes*	Merchant name, max 40 bytes (e.g. Amazon)
--merchant-url	Yes*	Merchant's HTTPS site
--merchant-country	Yes*	2-letter country code
--transaction-ref	No	Your order reference, max 50 bytes
--ext	—	*Instead of the merchant flags: JSON or @file.json with { "merchant": { "name", "url", "country_code" }, "transaction_reference_id"? }
--seconds	No	Validity, default 28800 (8 hours)

The response contains mandateId and approvalUrl. The user opens the link, picks a linked card and completes card verification. If approval fails because the merchant isn't recognised, check the merchant name, URL and country.

linked-card list

fluxa-wallet linked-card list [--limit 20] [--cursor <nextCursor>]

Lists the user's linked cards: id, brand, last4, expMonth, expYear, status, plus nextCursor for paging.

linked-card mandates

Usage	Shows
linked-card mandates	All of this agent's CARD_USD mandates with status and remaining amount
linked-card mandates --card <id>	Mandates approved on one linked card
linked-card mandates --host <host> --amount <cents>	Only approved mandates that can pay that amount at that merchant right now

linked-card subcard

fluxa-wallet linked-card subcard --mandate mand_xxx

Shows the payment credential issued under a mandate. The fields to use:

Field	Meaning
isReady	true when the mandate is approved and can pay. Wait for this before headless-checkout
approvalUrl	Set while the user still needs to approve
remainingAmount	Cents left under this mandate
validUntil	When the mandate expires
merchant	The merchant the mandate is limited to

If the readiness check can't complete, isReady stays false; retry shortly.

headless-checkout

fluxa-wallet headless-checkout --mandate mand_xxx --attempt wpa_xxx --billing @billing.json

Flag	Required	Description
--mandate	Yes	A ready CARD_USD mandate
--attempt	Yes	The payment attempt ID (wpa_…) from the merchant's checkout
--billing	No	JSON or @file: firstName, lastName, address1, address2, city, state, country, zip, phone, email

The result contains attempt.attemptId, attempt.status and attempt.actionUrl. If actionUrl is present, give it to the user to complete 3-D Secure, then confirm the order with the merchant.

Errors

Error	What to do
Linked cards are not available for this wallet	Not enabled for this account. Don't retry
card_mandate_not_active	The mandate isn't approved, is disabled, or has expired. Send the user approvalUrl from the error, or create a new mandate
card_execution_mode_mismatch	That mandate isn't a linked-card mandate. Pick one from linked-card mandates
invalid_attempt_id	Pass the wpa_… ID from the merchant checkout
Invalid CARD_USD mandate: <field> …	Fix the flag named in the message