3DS challenges

Some merchants ask for 3-D Secure (3DS) verification at checkout. When they do, AgentCard receives the one-time code or verification link for your card, and your agent reads it from these endpoints to finish the purchase.

Typical flow:

1. Submit the card at checkout.
2. When the merchant shows a 3DS prompt, call GET /cards/{cardId}/3ds/latest. Poll every few seconds if it is not there yet.
3. Enter the value (code) or open it (link) before expiresAt.

WARNING

3DS values are one-time secrets. Do not log them or share them outside the checkout they belong to. Returning a message marks it as read for the account.

3DS message object

{
  "cardId": "card_7Hq2LmX9pRt4",
  "type": "otp",
  "value": "482913",
  "expiresAt": "2026-10-27T13:25:00.000Z",
  "time": "2026-10-27T13:20:05.000Z"
}

Field	Description
cardId	The card the challenge is for.
type	otp (one-time code), auth_url (link to open to approve), or activation_code.
value	The code or link.
expiresAt	When the value stops working, if known.
time	When the challenge was received.

---

Latest challenge for a card

GET/api/v2/cards/{cardId}/3ds/latestBearer agent-vc

The newest challenge from the last 24 hours, or null.

curl https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/3ds/latest \
  -H "Authorization: Bearer $AGENT_VC"

{ "threeDS": { "cardId": "card_7Hq2LmX9pRt4", "type": "otp", "value": "482913", "expiresAt": "…", "time": "…" } }

CLI: fluxa-wallet card 3ds latest --id card_7Hq2LmX9pRt4

---

Recent challenges for a card

GET/api/v2/cards/{cardId}/3dsBearer agent-vc

Challenges from the last hour (up to 20), newest first.

curl https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/3ds \
  -H "Authorization: Bearer $AGENT_VC"

{ "threeDS": [ { "…": "3DS message" } ], "windowMinutes": 60 }

CLI: fluxa-wallet card 3ds latest_1h --id card_7Hq2LmX9pRt4

---

Challenges for all cards

GET/api/v2/3dsBearer agent-vc

Recent challenges across every card in the account (up to 50).

Query	Description
unreadOnly=true	Only messages not yet read by anyone in the account.

curl "https://agentcard.fluxapay.xyz/api/v2/3ds?unreadOnly=true" \
  -H "Authorization: Bearer $AGENT_VC"

Returns { "threeDS": [ … ] }.

---

Unread count

GET/api/v2/3ds/unread-countBearer agent-vc

Number of unread challenges in the account. Does not mark anything as read, so it is safe to poll.

curl https://agentcard.fluxapay.xyz/api/v2/3ds/unread-count \
  -H "Authorization: Bearer $AGENT_VC"

{ "unread": 1 }

---

Errors

Status	code	What to do
400	invalid_card_id	Use a card_… ID.
404	card_not_found	Check the card ID.