Get sandbox credentials
Sandbox credentials are a second client ID and client secret for your company. Copy them with Agentcard’s command-line tool:- SDK
- MCP
- API
Put the two lines in place of the production ones in your env file, After the client’s first call,
.env.local for Next.js and .env otherwise:agentcard.sandbox reads true.Run a purchase end to end
Send the same calls you send in live mode. Any new shopper id works: Agentcard adds the shopper on their first request. Ask for something, pick a product, and answer each question Agentcard asks, such as the address. When the cart is ready,next_action reads confirm.
Confirm the cart, and the sandbox stops at payment. The purchase ends declined with decline_code set to sandbox_mode, which means your run worked. Everything before it is what a live shopper sees.
A store can price the tax only at the confirm. Then the first confirm comes back with a new total instead of paying, as it would in live mode, and you confirm again.
- SDK
- MCP
- API
Run the walkthrough that ships with the package. It connects a test shopper, asks for a restaurant table, picks one and confirms it, with no model involved:The sandbox refuses the booking itself, so the last answer is Then send your own agent “two packs of AA batteries from Amazon” as a test shopper, and look for product cards, a short reply and a cart. The buy tool’s answer to the shopper’s yes reads
declined with decline_code: sandbox_unavailable, and the run ends with:status: 'declined' and decline_code: 'sandbox_mode'.Save a test card
Some stores are bought through their own checkout page, which Agentcard fills in. There the shopper pays with a card saved in the Vault, Agentcard’s page where the shopper saves their card and approves a payment, so a sandbox shopper needs a test card first. A confirm at such a store for a shopper with no test card is refused withtest_card_missing, and the store keeps the cart:
111111. Save any of Stripe’s published test cards. Then send the same confirm again while the store still keeps the cart.
- SDK
- MCP
- API
The buy tool’s call fails with the refusal’s message, which your model reads. The error’s
cause holds the AgentcardApiError, whose code is test_card_missing. Make the Vault link with mintVaultLink():sandbox.ts
Approve a test payment
With a test card saved, the confirm asks the shopper to approve the payment on the Vault’s approval page. Open the page and approve. Then send the same confirm again, and the answer says the approval went through and the card was never sent to the store. No order exists and nothing is charged.- SDK
- MCP
- API
The buy tool’s answer reads
status: 'approval_sent' and hands sendLink a link whose kind is approval. After the shopper approves, the next answer carries decline_code: 'sandbox_mode'.Choose how a confirm ends
Addsandbox_outcome to a sandbox confirm to see how your app handles each way a purchase can end, before any live order. Set it to placed, failed or delayed:
livemode: false.
A
delayed confirm reads declined only because no order exists yet. Don’t ask the shopper again: order.placed follows.
A placed order reads back like a live one, in the conversation’s orders and from GET /buy/orders/{order_id}, as Read where an order is shows.
A delayed order answers with reply set to:
order.placed, then read the conversation again: the order is there.
A confirm with sandbox_outcome is refused in three cases, and nothing is charged in any of them:
A request with live credentials is refused like this: