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:Register your Stripe Link app
Apply for your own Stripe Link app through Stripe’s Link Agent Wallet application form. The form is how your company gets its own Stripe Link client. Stripe’s Link OAuth guide 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: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:Mount the sign-in routes
Install Stripe Link’s SDK beside Agentcard’s: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:
link.ts
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.
app/api/link/connect/route.ts
app/api/link/callback/route.ts
/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:
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:
link-store.ts
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:
Disconnect a shopper
End a shopper’s Stripe Link sign-in from your own settings page:settings.ts
Run the sign-in steps yourself
A server with its own routing callslinkConnect and its steps one at a time. linkConnect takes the same options as linkRoutes, with redirectUri required and no shopperOf:
Read a failed sign-in
A sign-in that connects nothing lands the shopper onreturnTo with the reason in the address:
linkConnect throws the same reason as a LinkConnectError, whose code you read and whose message names the step: