Skip to main content
This guide takes you from zero to a first purchase with the Vault. You will store a test card, attach Agentcard to an agent browser, and let the user approve a payment with their passkey. The flow in one line: the user stores a card once → your agent shops in a browser and submits a placeholder card → Agentcard pauses the payment → the user approves on their device → that device pays with the real card → your agent confirms the order. Step 1 happens once per user. Steps 2 to 4 happen on every purchase. Presets are optional: once it works, you can attach a preset to one of a user’s cards, and only that card’s purchases are filtered.

1. Get your credentials

You need an Agentcard organization client_id and client_secret. Create them in the dashboard and exchange them for an access token:
Use the returned token as $ORG_TOKEN below. Sandbox credentials create sandbox sessions and sandbox authorizations, so start there. When the rehearsal works, go to production.

2. Store a card

Create a vault session and send the user the link wherever you already talk to them: iMessage, WhatsApp, your app.
The user opens the link, types their card, and saves it with a passkey (Face ID, Touch ID, or fingerprint). A master password is offered afterwards as a backup. The page asks for a master password before the card is stored when the card will open only in this browser. The card is encrypted on their device before it leaves. When they finish, you receive a vault.session_linked webhook with their user_id, or you poll the session until its status is linked. Store that user_id, you need it on every purchase. For a test run, store a test card: any of Stripe’s published test cards, any future expiry, any CVC. More on adding cards →

3. Attach Agentcard to your browser

Install the SDK next to your browser provider. This example uses KERNEL; Browserbase and any CDP browser work the same way.
Attach before your agent reaches the payment form. The SDK watches the page for the payment processor’s request.
The init script keeps the store from starting a service worker, which would stop the SDK from pausing the card request. Block service workers explains what changes for the store. More on creating a cart →

4. Complete the purchase

Let your agent shop as usual. At checkout it should fill the card form with placeholder data, any of Stripe’s published test cards, and submit. The Agentcard SDK intercepts the processor request and pauses it. onApprovalUrl fires with a link; send it to the user. They approve with their passkey, their device sends the real card to the processor, and the paused request resumes with the real response. Then confirm the order with the merchant before you tell the user anything:
More on completing a purchase →

Try it against a store that always works

shop.agentcard.sh is a demo store on Stripe test mode, kept running for exactly this rehearsal. Add a product, submit the card form with the placeholder card, approve on the device that holds your passkey, and the order completes with a real test-mode charge.

Go to production

The flow does not change. There is no separate production host, and the mode comes from the credential you call with, never from the URL (more on credentials →). Create a production client in the dashboard under Settings → Developers → Credentials and mint $ORG_TOKEN from that pair instead of the sandbox one. Three things from your sandbox run do not carry over. Sandbox and production users are separate. A sandbox user_id sent with production credentials is refused with a 404:
In the Vault that means step 2 again: create a vault session with the production token, send the user its link, and store a real card. A session minted in one mode is a 404 in the other, so poll a production vs_ id with the production credentials that created it. A webhook endpoint belongs to one mode, so add a production endpoint or vault.session_linked never arrives live. Steps 3 and 4 change in one place: point your agent at the store you sell through, and set merchant to the name that store shows the user. shop.agentcard.sh stays on Stripe test mode whatever credentials you call with, so it never charges a real card. At your own store the purchase charges the user’s real card.

Keep going

Adding a card

Open vs connected sessions, webhooks vs polling, returning users.

Creating a cart

Browsers, SDK options, and the Commerce SDK alternative.

Completing a purchase

Approval, reconciliation, webhooks, supported processors.