Skip to main content
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:
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. 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:
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:
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:

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
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.
app/api/link/connect/route.ts
app/api/link/callback/route.ts
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:
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:
link-store.ts
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:

Disconnect a shopper

End a shopper’s Stripe Link sign-in from your own settings page:
settings.ts
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:

Read a failed sign-in

A sign-in that connects nothing lands the shopper on returnTo with the reason in the address:
linkConnect throws the same reason as a LinkConnectError, whose code you read and whose message names the step: