Read the credentials
Ask for them when your agent is at the payment form, not before:balance_cents is there, and the number isn’t.
When the user has asked to approve each reveal, the read is refused with credentials_protected. Your server can’t read that card.
Show your user their card
When your user asks to see their card in your app, open Agentcard’s card page for them. The number, expiry and CVC reach only their browser. Your server and your app’s code never hold them. Create a reveal session from your server at the moment they ask:url in your user’s browser, in a frame inside your app or in a new window. The page shows the last four digits, and the full details once your user chooses Show card details. The details stay on screen for one minute.
Each session shows the card once and expires after five minutes. Create a new session every time your user asks. To change the window, send expires_in in seconds, from 60 to 900.
To show the page inside your app, register the sites allowed to frame it:
allow="clipboard-write" to your frame so the Copy buttons work. Without it, the page selects the text for your user to copy.
A session is refused for the same reasons as a credentials read. A closed card, for example:
Pay
Type the credentials into the checkout. The card authorizes up to itsspend_limit_cents, and declines anything above it or outside a merchant lock. Your server receives transaction.authorized when money moves and approval.requested when a purchase needs a human first.
To give your agent a buy tool for the merchants Agentcard already covers, see Agentcard’s Commerce SDK.
What happens after a charge
- Single-use cards close themselves after the first approved charge.
closed_reasonisused. - Multi-use cards stay open until their limit is spent or you close them.
- Refunds post back to the card that paid. The balance returns to the user.
- Tokenback: settled spend earns tokens, 1 token per cent.
Manage a card
Close a card from your server when the purchase falls through:
Webhooks
Register a webhook endpoint and subscribe to what you need:
React to webhooks, not to the conversation. The agent saying it paid is a claim.
transaction.authorized is a fact.
List your transactions
Read every charge on your company’s cards, and every Vault checkout your agents opened, with your platform token:id is the transaction_id a transaction.* webhook carries, so an event and its row match. A simulated sandbox charge names no currency, so currency and amount_display read null. The API reference lists every filter.