Skip to main content
Run a whole purchase before you spend any money. The sandbox, Agentcard’s test mode, searches real stores, builds real carts at the stores’ real prices, and stops at payment. No order is placed and nobody is charged.

Get sandbox credentials

Sandbox credentials are a second client ID and client secret for your company. Copy them with Agentcard’s command-line tool:
Every call made with sandbox credentials runs in the sandbox. Nothing else changes: the address, the calls and the tools stay the same.
Put the two lines in place of the production ones in your env file, .env.local for Next.js and .env otherwise:
After the client’s first call, 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.
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 declined with decline_code: sandbox_unavailable, and the run ends with:
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 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 with test_card_missing, and the store keeps the cart:
Make a Vault link for the same shopper and open it. The Vault asks for a code to connect the shopper, and in the sandbox that code is always 111111. Save any of Stripe’s published test cards. Then send the same confirm again while the store still keeps the cart.
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.
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

Add sandbox_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:
The confirm ends the purchase at once, with no approval link for the shopper. No store receives the order, no card is made and nothing is charged. Your server still gets the order events a live order sends, marked 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:
Wait for 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:
A confirm that names several carts is refused:
A confirm of one cart at a store’s own checkout page is refused with the same code:
Where Agentcard has turned the option off for your company, the same confirm is refused before any cart is read:

Know what differs from live

Go live

Swap your sandbox client ID and secret for live ones, and keep every call the same. Your test shoppers do not carry over: each live shopper starts with their first request, and the first confirm they approve places a real order and charges their card. Test the full flow with your own card first. Before your first live order, choose Go live in the dashboard’s banner, and choose how to pay Agentcard’s fee of 1% of each live purchase. Read a refusal lists every error you can meet on the way.