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.
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.