Skip to main content
Once a shopper connects their Stripe Link wallet, the buy tool lists Stripe Link as a way to pay for each cart it can pay. 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:
agentcard.ts
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:
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:
agentcard.ts
wallets takes ['vault'], ['link'], ['vault', 'link'] or ['link', 'vault']. The wallet the shopper paid with last shows first. Pass lastUsedFirst: false to keep your order. Each wallet’s label is the button’s words: “Your card” for the Vault and “Stripe Link” for Link. 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:
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:
Spread buyWallets into buyTool, or pass wallet: { link }. buyTool refuses a Stripe Link client with a wallets list that leaves Stripe Link out:
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:
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:
chat.ts
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: When the shopper taps a button, call buy.payWith:
chat.ts
The wallet methods exist only on a tool built with wallets, so TypeScript types them as optional. A tap on either wallet only chooses it. The answer carries that wallet’s Approve purchase step and sends nothing to Agentcard or Stripe Link, so a stray tap never pays and never opens a card step. The shopper’s press of Approve is their yes. 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.
When the shopper presses Approve, call buy.approve with the step’s wallet:
chat.ts
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. For the Vault, buy.approve sends the shopper’s yes, and the answer carries the Vault’s add-a-card page when no card is saved, else its passkey page, as in “Approving a purchase”. Reserve the pop-up in the press’s click handler when approvalOpensWindow(step) from @agent-cards/commerce-sdk/browser is true, so the page opens with no second tap. 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:
Stripe Link pays for a hotel, a rental car or a flight the shopper books through Agentcard. The shopper approves the trip’s total in Stripe Link, the same Approve purchase step as a store’s cart, and the travel seller charges that approval. One approval covers one booking at its quoted total. A trip with a flight, a hotel and a car asks for three approvals, one per booking, and wallet_progress counts them as it does for stores, such as “1 of 3 approved”.

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. 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. Agentcard turns this on company by company. Until it reaches yours, Stripe Link pays these stores as the rest of this page describes. Once it does, Agentcard offers Stripe Link at Amazon, Walmart, Best Buy and the other stores it orders from for the shopper as soon as the store prices the cart. Before that, the cart shows its estimate and Stripe Link waits for the store’s total. The shopper approves the store’s total plus a $1 order fee in Stripe Link. The seller charges that amount when the order goes in, and returns anything the store did not charge to the shopper’s Stripe Link once the order is placed. When the store cannot place the order, the seller returns all of it. The shopper reads both in the chat:
Stripe Link takes up to $499 for one order. Above that, the wallet list shows Stripe Link as unable to pay, and the shopper can pay with the Vault when your app offers it:
When the store raises its total before the order goes in, the seller returns the charge in full, and Agentcard asks the shopper once to approve the new total. A cart the store sends as several orders asks the shopper for one Stripe Link approval per order. Each approval places its order, in turn. When the store raises the total of one of those orders, the seller returns its charge in full, and the shopper hears that it did not go in. 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:
app/api/agentcard/route.ts
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:
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: A confirm Agentcard does not take as a Stripe Link payment for your company throws an AgentcardApiError with code: link_payment_unavailable:

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.
agentcard.ts
  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.