> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Paying with a Stripe Link wallet

> Hand the shopper's wallets to the buy tool, show the wallet choice and the Approve purchase step, and read how a Stripe Link payment ended.

Once a shopper has connected their Stripe Link wallet, the buy tool offers it beside the Vault. The shopper taps a wallet under the cart, approves the purchase in that wallet, and Agentcard places the order. Nothing is charged until they approve, and a payment that fails offers the other wallet in the same message.

"Connecting a shopper's Stripe Link wallet" sets up the sign-in this page builds on.

## Hand the wallets to the buy tool

Spread `link.buyWallets(shopperId, wallets)` into `buyTool`. List the wallets your app offers in the order the shopper sees them:

```ts agentcard.ts theme={null}
import { AgentcardClient, buyTool, type BuyTool } from '@agent-cards/commerce-sdk';
import { link } from '@/link';

export const agentcard = new AgentcardClient({
  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
});

/** The buy tool for one shopper, built for each request from the chat's saved state. */
export async function buyFor(shopperId: string): Promise<BuyTool> {
  return buyTool({
    agentcard,
    externalUserId: shopperId,
    state: chatState, // your store: get, set and setIfAbsent, such as Redis
    ...(await link.buyWallets(shopperId, ['vault', 'link'])),
  });
}
```

`buyWallets` answers the tool's `wallet` and `wallets` options together. A shopper who has connected Stripe Link gets their Stripe Link client and both wallets. A shopper who has not gets the Vault alone:

```json theme={null}
{ "wallets": ["vault"] }
```

With `['link']` alone, a shopper who has not connected gets `{}`. A tool built from `{}` names no wallet, so it pays with the Vault, as a tool built with no wallets always has. Check for Stripe Link before you build the tool, and send that shopper to your connect route instead:

```ts agentcard.ts theme={null}
const wallets = await link.buyWallets(shopperId, ['link']);
if (!wallets.wallet) return redirectTo('/api/link/connect'); // your code: the shopper connects Link first
const buy = buyTool({ agentcard, externalUserId: shopperId, state: chatState, ...wallets });
```

`wallets` takes `['vault']`, `['link']`, `['vault', 'link']` or `['link', 'vault']`. Pass `lastUsedFirst: true` to show the wallet the shopper paid with last ahead of your order. A tool built with neither `wallet` nor `wallets` pays with the Vault, as it always has.

A tool with a Stripe Link wallet and `state` needs a store with `setIfAbsent(key, value, ttlSeconds)`, as Redis `SET NX EX` gives it. The tool claims an approved Stripe Link payment through it before it confirms, so two servers that resume the same chat confirm the payment once. Without it, `buyTool` refuses:

```text theme={null}
TypeError: A Link wallet with state needs a store with setIfAbsent(key, value, ttlSeconds), as Redis SET NX EX gives it, so an approved Link payment is confirmed once across servers.
```

`buyTool` checks the wallets when you build it, so a mistake fails before the shopper's first message:

`buyTool` refuses a `wallets` list that names `link` with no Stripe Link client:

```text theme={null}
TypeError: wallets names 'link', so pass the shopper's Link client too: wallet: { link }, where link is new Link({ getAccessToken }) from '@stripe/link-sdk'.
```

Spread `buyWallets` into `buyTool`, or pass `wallet: { link }`.

`buyTool` refuses a Stripe Link client with a `wallets` list that leaves Stripe Link out:

```text theme={null}
TypeError: wallet: { link } pays only when wallets names 'link': add 'link' to wallets, or leave wallets out to pay with Link alone.
```

Add `'link'` to `wallets`, or leave `wallets` out to pay with Stripe Link alone.

`buyTool` refuses a `wallets` list that names a wallet twice, or one the SDK does not know:

```text theme={null}
TypeError: Pass wallets as the wallets your shoppers can pay with, in the order they see them: ['vault'], ['link'], ['vault', 'link'] or ['link', 'vault'].
```

Name each of `'vault'` and `'link'` at most once.

## Show the wallet choice

An answer with carts to pay carries `wallets`, one entry per wallet you offer, in the order to show them. Show each as a button under the cart:

```ts chat.ts theme={null}
const buy = await buyFor(shopper.id);
const turn = buy.turn(message, {
  sendLink: (link) => deliverLink(shopper.id, link), // your code
  onResult: (result) => {
    if (result.wallets) showWalletButtons(shopper.id, result.wallets, result.swipe); // your code
    if (result.approval) showNextStep(shopper.id, result.approval); // your code
  },
});
```

| Field | What it carries |
| - | - |
| `wallet` | `vault` or `link`. |
| `fits` | `true` when the wallet can pay every cart in the answer. |
| `reason_text` | The line to show beside a wallet that cannot pay, such as "Over Link's limit". `null` when it fits. |
| `last_used` | `true` when the shopper paid with this wallet last time. |
| `setup_needed` | The Vault only: `true` when the shopper has no card saved yet, so its step adds one first. |

Show a wallet that cannot pay as a disabled button with its `reason_text`. The shopper keeps the product and the cart, and picks the other wallet:

| `reason` | `reason_text` |
| - | - |
| `store_cannot_take_link` | Stripe Link isn't available for this order yet |
| `over_limit` | Over Link's limit |
| `over_daily_limit` | Over Link's daily limit |
| `over_monthly_limit` | Over Link's monthly limit |
| `ships_outside_us_canada` | Ships outside the US and Canada |

When the shopper taps a button, call `buy.payWith`:

```ts chat.ts theme={null}
const answer = await buy.payWith!('link'); // or 'vault'
```

The wallet methods exist only on a tool built with wallets, so TypeScript types them as optional.

A tap on the Vault sends the shopper's yes, with its add-a-card or approval step as before. A tap on Stripe Link answers the Approve purchase step and asks Stripe Link for nothing yet. A shopper who types "yes" instead pays with the first wallet in the list that fits.

## Show the Approve purchase step

The answer's `approval` is the step the shopper approves, in the same shape for both wallets. Show it as one card: `eyebrow` above `title`, then `line`, then one button reading `button`.

```json theme={null}
{
  "wallet": "link",
  "store": "Amazon",
  "eyebrow": "Next step · approve in Link",
  "title": "Approve purchase",
  "line": "$8.94 estimated at Amazon, up to $18.31 with tax and shipping. Nothing is charged until you approve.",
  "button": "Approve",
  "index": 1,
  "count": 1,
  "approval_url": null
}
```

When the shopper presses Approve, call `buy.approve` with the step's wallet:

```ts chat.ts theme={null}
const pressed = await buy.approve!({ wallet: step.wallet }); // step: the approval the last answer carried
// pressed.approval.approval_url is Link's page: open it in your approval pop-up
```

`approval_url` is `null` until the press. For Stripe Link, `buy.approve` asks Stripe Link for the payment, and the answer carries the step again with Stripe Link's page to open. The shopper approves there, in Stripe Link. Call `buy.awaitWallet()` to wait for their answer: once they approve, the tool confirms the cart with Agentcard, which pays the store. The Vault's step carries its passkey page, as in "Approving a purchase".

Stripe Link asks for one approval per store. With carts at several stores, the step names one store at a time with `index` and `count`, and `wallet_progress` carries the count to show, such as "1 of 2 approved". After a Stripe Link purchase across several stores, and only when you offer the Vault, the next answer carries `wallet_tip` once. Show it as a small grey note under the answer:

```text theme={null}
For faster checkout next time, use a single approval with the Vault.
```

## Let the shopper swipe the cart

An answer with a cart carries `swipe`, which says what a swipe on the cart's row does now. A swipe right does what the step's main button does for the chosen wallet, and a swipe left empties the cart. Tint the row with the color of `swipe.right.wallet`, so the shopper sees which wallet a swipe right pays with.

| `swipe.right.action` | What to run |
| - | - |
| `pay_with` | `buy.payWith(swipe.right.wallet)` |
| `approve` | `buy.approve({ wallet: swipe.right.wallet })`, or open the step's page when it has one |
| `setup` | `buy.payWith('vault')`, which sends the add-a-card step |
| `check_out` | Send the shopper's words "Check out", since the cart is not at its total yet |
| `none` | Spring the row back and show `swipe.right.reason`, such as "Choose how to pay first" |

With both wallets offered, a swipe right waits for the shopper's tap on a wallet and never picks one for them. Show `swipe.right.label` under the row as the shopper pulls it.

A swipe left with `swipe.left.action` set to `clear_cart` calls `buy.clearCart({ store })`. Agentcard cancels the Stripe Link payments still waiting on that store's cart and takes each line out at the store. Left out, `store` empties every cart. The answer says how many Stripe Link payments it canceled, and carries the carts left and their swipe.

## Read how a Stripe Link payment ended

Agentcard tells your server how the store answered. Pass every message to `buy.walletOutcome`, and post its `reply` in place of the message's text:

```ts app/api/agentcard/route.ts theme={null}
const webhook = agentcardWebhook({
  secret: process.env.AGENTCARD_WEBHOOK_SECRET ?? '',
  onMessage: async (shopperId, message) => {
    const buy = await buyFor(shopperId);
    const outcome = await buy.walletOutcome?.(message);
    await postToChat(shopperId, outcome?.reply ?? message.text); // your code
  },
});
```

| `charge` | What happened | What the shopper reads |
| - | - | - |
| `placed` | The store took the order. | The message's own text. |
| `none` | The store's checkout did not take Stripe Link's card. Agentcard cancels the Stripe Link payment at once, so nothing is charged. | "Target's checkout didn't take the Link card, so nothing was charged. Want me to try again?" |
| `maybe` | The store has not answered yet. Nothing is canceled. | "Your order at Target may have gone through. We're checking with the store, so don't order it again yet." |

`walletOutcome` answers `null` for a message about no Stripe Link purchase. On `none`, `outcome.approval` is a step whose button reads "Try again", and `buy.approve` pays the cart again with a new Stripe Link approval.

A Stripe Link payment that fails with nothing charged inside a turn answers in one message, and carries `wallet_fallback`. Show its `actions` as buttons under the reply, in their order:

```text theme={null}
Link couldn't pay at Target, nothing was charged. Pay with the Vault instead?
[Pay with the Vault] [Try again]
```

The Vault is offered only when you offer it and it fits the cart. "Pay with the Vault" calls `buy.payWith('vault')`, and "Try again" calls `buy.approve({ wallet: 'link' })`. The tool never switches wallets on its own. With Stripe Link alone, the shopper sees Try again only.

## Handle a refusal

A refusal answers `needs_input` with the reason in `reply` and the code in `error_code`. Nothing is charged on any of them. Post `reply` as it is:

| `error_code` | What it means | What the shopper reads |
| - | - | - |
| `wallet_not_chosen` | The shopper pressed Approve with both wallets offered and none chosen. | "Choose how to pay first, so nothing was charged." |
| `wallet_not_offered` | Your app does not offer the wallet the shopper tapped. | "This app doesn't take payment with Link, so nothing was charged." |
| `wallet_does_not_fit` | The tapped wallet cannot pay these carts. | "Link can't pay for this purchase (Over Link's limit), so nothing was charged." |
| `link_no_payment_method` | The shopper's Stripe Link wallet holds no card. | "Your Link wallet has no card yet. Add one in the Link app, then say yes again." |
| `link_store_address_missing` | Agentcard cannot name the store's web address for Stripe Link to pay. | "Stripe Link isn't available for this order yet, so nothing was charged." |
| `link_cart_changed` | The shopper changed or emptied the cart while Stripe Link was asked. | "The cart changed while Link was asked, so nothing was charged. Say yes again to pay for the cart as it is now." |
| `link_payment_failed` | Stripe Link did not take the payment. | "Link didn't take the payment, so nothing was charged. Want to pay another way?" |
| `link_payment_refused` | The store's checkout refused the Stripe Link payment. | "Target's checkout didn't take the Link payment, so nothing was charged." |
| `link_payment_mismatch` | Stripe Link's approval names another amount, currency or store than the cart, so the tool canceled it. | "Target's checkout didn't take the Link payment, so nothing was charged." |
| `link_claim_unavailable` | The shopper approved, and the tool could not confirm the approval yet. | "Your Link approval is in, and nothing was charged yet. Agentcard couldn't confirm it just now, so it tries again on the next check." |

A confirm Agentcard does not take as a Stripe Link payment for your company throws an `AgentcardApiError` with `code: link_payment_unavailable`:

```text theme={null}
AgentcardApiError: Agentcard does not take a Link payment here. Nothing was charged.
```

## Check it in test mode

Pass `test: true` with the shopper's Stripe Link client, and Stripe Link issues test-mode payments: the shopper approves as usual, and Stripe Link makes no real card.

```ts agentcard.ts theme={null}
const { wallet, wallets } = await link.buyWallets(shopper.id, ['vault', 'link']);
const buy = buyTool({ agentcard, externalUserId: shopper.id, state: chatState, wallets, ...(wallet ? { wallet: { ...wallet, test: true } } : {}) });
```

1. Connect a test shopper through your connect route, and check that they land on `returnTo` with `link=connected`.
2. Ask for one item. Check that the answer's `wallets` lists the Vault and Stripe Link, in your order.
3. Tap Stripe Link, then Approve. Check that the step's `approval_url` opens Stripe Link's page, and approve there.
4. Check that `buy.awaitWallet()` answers with `status` `placing` or `order_placed`.
5. Ask again, tap Stripe Link, and decline in Stripe Link. Check that the reply says nothing was charged and the cart is still there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.