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.

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.