Skip to main content
An issued card works like any card: your agent types the number, expiry and CVC into a merchant’s checkout. What is different is what happens around it. Credentials are revealed on demand, single-use cards close themselves, and every charge reaches your server as a webhook.

Read the credentials

Ask for them when your agent is at the payment form, not before:
Never write the number or CVC to logs, error reports, or analytics. Agentcard records every read. To check the balance, get the card instead: 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:
Open 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:
A site you have not registered can’t frame the page, so the page opens only in its own window there. Add 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 its spend_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_reason is used.
  • 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:
Use the list to reconcile, or to catch up on what your webhook endpoint missed. The 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.

Sandbox

Test cards are issued instantly, carry credentials, and are not accepted by real merchants. Use them to exercise your agent’s checkout code against a test storefront such as shop.agentcard.sh on Stripe test mode. The reveal, close and webhook flows are identical to live. To test what your code does with a charge, simulate one with a sandbox credential. No merchant is involved, and your webhook endpoints get the same events a real charge sends:
To walk each step yourself, place a hold, then capture or reverse it, and refund a cleared charge.