> ## 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

# Connecting a shopper's Stripe Link wallet

> Register your own Stripe Link app, keep its secret on your server, and sign a shopper in to their Stripe Link wallet with two route handlers.

Let your shoppers pay with their own Stripe Link wallet, beside the Agentcard Vault or in its place. Your server signs a shopper in to Stripe Link once. From then on the buy tool asks Stripe Link to approve each purchase, and Agentcard pays the store with the one-time card Stripe Link issues for it.

You register the Stripe Link app with Stripe yourself. The shopper's consent page names your company, and each shopper's Stripe Link sign-in stays on your server. "Paying with a Stripe Link wallet" covers what happens after the sign-in.

## Choose your wallets

Offer the Vault, Stripe Link, or both, in the order your shoppers see them. Choose them in your dashboard, under the Commerce SDK setup's "Choose your wallets" step, by ticking Agentcard Vault, Stripe Link, or both.

Stripe Link pays at store checkouts across the web. Each answer says which wallets can pay its carts. The shopper approves each store's payment in Stripe Link, with the cards they already keep there.

When you tick Stripe Link alone, the dashboard warns you:

```text theme={null}
Each cart says which wallets can pay it. Carts Stripe Link isn't available for check out with the Vault.
```

A cart Stripe Link isn't available for shows Stripe Link as a disabled button with its reason, and the shopper cannot check out that cart.

## Register your Stripe Link app

Apply for your own Stripe Link app through Stripe's [Link Agent Wallet application form](https://docs.google.com/forms/d/1frwbtMaUUAaMMv0rHEk_qCvKUHJUxHCr8vkLknnBS9w/viewform). The form is how your company gets its own Stripe Link client. [Stripe's Link OAuth guide](https://docs.stripe.com/agentic-commerce/link-cli/oauth) describes the sign-in the app runs.

List every redirect URI your app will use on the form, up front. Stripe Link matches a redirect URI exactly, so a host you leave off gets no consent page. Give the address of your callback route on each host your app runs on:

```text theme={null}
https://shop.example.com/api/link/callback
https://staging.shop.example.com/api/link/callback
https://shop-dev.ngrok.app/api/link/callback
```

Stripe Link refuses a `localhost` redirect URI. To test on your own machine, serve your app through a public tunnel, such as ngrok, and list the tunnel's address on the form. Stripe adds a redirect URI to your Stripe Link app only on request: you cannot edit the list yourself, so ask Stripe to add one when your app gains a host.

The SDK asks for the `payment_methods.agentic` and `userinfo:read` scopes. Stripe answers with a client ID and a client secret. Your publishable key, `pk_live_...` or `pk_test_...`, comes from your Stripe account.

## Keep the client secret on your server

Store the client ID, the client secret and the publishable key in your own secret store, and read them on your server only:

```bash theme={null}
LINK_CLIENT_ID=...
LINK_CLIENT_SECRET=...
LINK_PUBLISHABLE_KEY=pk_live_...
```

The client secret never goes into a browser bundle or a mobile app. The sign-in helpers run on your server, and no error they throw carries the secret, a shopper's token or a sign-in code.

Your dashboard also asks for the three keys, under "Connect your Link app" in the same step. Agentcard seals the client secret before it stores it and never shows it again: the dashboard reads "Link app connected." and shows only the last four characters of the client ID. Your server still reads its own copy, because the SDK takes the secret from your server, never from Agentcard.

The dashboard refuses keys it can tell are wrong before it saves them:

| What you see | What to do next |
| - | - |
| `Fill in all three keys.` | Paste the client ID, the client secret and the publishable key. |
| `The publishable key starts with pk_live_ or pk_test_.` | Paste the publishable key from your Stripe account, not the client secret. |
| `Link didn't accept those keys. Check them in your Link app and try again.` | Copy the three keys again from the Stripe Link app Stripe registered. |
| `Only an owner or admin of this company can connect the Link app.` | Ask an owner or admin of your company to paste the keys. |

## Mount the sign-in routes

Install Stripe Link's SDK beside Agentcard's:

```bash theme={null}
npm install @agent-cards/commerce-sdk @stripe/link-sdk
```

`linkRoutes` answers the two route handlers a shopper's Stripe Link sign-in needs. Each takes a Web `Request` and answers a `Response`, so they mount as Next.js route handlers as they are, and in Bun or Deno:

```ts link.ts theme={null}
import { Link } from '@stripe/link-sdk';
import { linkRoutes } from '@agent-cards/commerce-sdk';

export const link = linkRoutes({
  clientId: process.env.LINK_CLIENT_ID!,
  clientSecret: process.env.LINK_CLIENT_SECRET!,
  publishableKey: process.env.LINK_PUBLISHABLE_KEY!,
  Link,
  store: linkStore, // where shoppers' Link sign-ins are kept, below
  shopperOf: (request) => signedInShopper(request), // your own session
  returnTo: '/chat',
});
```

Put `link.ts` in your project's root folder, or in `src/` when your app keeps its code there. The route handlers below and the buy tool in "Paying with a Stripe Link wallet" import it as `@/link`, the import alias a Next.js app sets up in `tsconfig.json`.

```ts app/api/link/connect/route.ts theme={null}
import { link } from '@/link';
export const GET = link.connect;
```

```ts app/api/link/callback/route.ts theme={null}
import { link } from '@/link';
export const GET = link.callback;
```

Send the shopper to `/api/link/connect`. They approve on Stripe Link's consent page, Stripe Link sends them back to the callback route, and they land on `returnTo` with the outcome in the address:

```text theme={null}
https://shop.example.com/chat?link=connected
```

A shopper who is already connected goes straight to `returnTo` with `link=connected`, with no consent page.

`shopperOf` reads the shopper from your own session cookie or header. The shopper never comes from the address, so a consent link forwarded to someone else can never connect their Stripe Link wallet to the sender's account.

The callback path is `/api/link/callback` unless you pass `callbackPath`. The redirect URI is the request's own origin plus that path, so one setup serves every host you listed with Stripe. Pass `redirectUri` to fix one address instead. To land the shopper on your own page, pass `onDone`, which receives the outcome and the request and answers a `Response`.

## Keep the sign-ins in a store

`store` holds each shopper's Stripe Link sign-in, and each sign-in that is still under way, as JSON strings. Redis, a database row or a `Map` fits. A `Map` serves one server instance:

```ts link-store.ts theme={null}
import type { LinkConnectStore } from '@agent-cards/commerce-sdk';

const kept = new Map<string, string>();

export const linkStore: LinkConnectStore = {
  get: async (key) => kept.get(key) ?? null,
  set: async (key, value) => { kept.set(key, value); },
  del: async (key) => { kept.delete(key); },
};
```

With more than one server instance, give the store three one-step operations as well: `setIfAbsent`, `delIfEquals` and `compareAndSet`. A short Lua script each in Redis, or a conditional write in a database, provides them. Two instances then never refresh one shopper's Stripe Link token at once and lose it. Give all three or none, or `linkRoutes` refuses the store when you build it:

```text theme={null}
TypeError: linkConnect takes store.setIfAbsent, store.delIfEquals and store.compareAndSet all together or none: a grant shared by several server instances needs all three.
```

## Disconnect a shopper

End a shopper's Stripe Link sign-in from your own settings page:

```ts settings.ts theme={null}
await link.disconnect(shopper.id);
```

Your server asks Stripe Link to revoke the sign-in, then deletes it from your store. The shopper's next Stripe Link purchase sends them to the connect route again.

## Run the sign-in steps yourself

A server with its own routing calls `linkConnect` and its steps one at a time. `linkConnect` takes the same options as `linkRoutes`, with `redirectUri` required and no `shopperOf`:

| Step | What it does |
| - | - |
| `authorizeUrl(shopperId)` | Answers Stripe Link's consent page for the shopper. The sign-in stays open for 10 minutes. |
| `handleCallback({ code, state, error, shopperId })` | Finishes the sign-in. Pass the shopper from your own session, never from the callback's address. |
| `client(shopperId)` | Answers the shopper's Stripe Link client, or `null` when they have not connected Stripe Link. |
| `getAccessToken(shopperId)` | Answers the shopper's Stripe Link access token, refreshed when it runs out within a minute. |
| `disconnect(shopperId)` | Revokes the sign-in at Stripe Link, then deletes it. |

## Read a failed sign-in

A sign-in that connects nothing lands the shopper on `returnTo` with the reason in the address:

```text theme={null}
https://shop.example.com/chat?link=unknown_state
```

`linkConnect` throws the same reason as a `LinkConnectError`, whose `code` you read and whose message names the step:

```text theme={null}
LinkConnectError: Link callback failed: declined (access_denied)
```

| `link` or `code` | What it means | What to do next |
| - | - | - |
| `no_shopper` | The request carried no signed-in shopper. | Sign the shopper in to your app, then send them to the connect route. |
| `declined` | The shopper declined on Stripe Link's consent page. | Offer the Vault, or the connect route again. |
| `unknown_state` | The callback names a sign-in this server never started, or one another shopper started. | Send the shopper to the connect route again. |
| `expired_state` | The sign-in started more than 10 minutes ago. | Send the shopper to the connect route again. |
| `missing_code` | Stripe Link sent the shopper back with no code. | Send the shopper to the connect route again. |
| `link_error` | Stripe Link refused the sign-in. `linkError` holds Stripe Link's own code, such as `invalid_grant`. | Check that the client ID, the secret and the redirect URI match the app Stripe registered. |
| `link_unreachable` | Stripe Link did not answer. | Send the shopper to the connect route again. |
| `not_connected` | The shopper has no Stripe Link sign-in, or ended it at Stripe Link. | Send the shopper to the connect route. |
| `refresh_busy` | Another server instance held the shopper's sign-in longer than a refresh takes. | Read the token again. |


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