Hand the wallets to the buy tool
Spreadlink.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:
['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']. 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:
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:
buyWallets into buyTool, or pass wallet: { link }.
buyTool refuses a Stripe Link client with a wallets list that leaves Stripe Link out:
'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:
'vault' and 'link' at most once.
Show the wallet choice
An answer with carts to pay carrieswallets, 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
Show the Approve purchase step
The answer’sapproval 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.
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. 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:
Let the shopper swipe the cart
An answer with a cart carriesswipe, 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.
Read how a Stripe Link payment ended
Agentcard tells your server how the store answered. Pass every message tobuy.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:
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 answersneeds_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
Passtest: 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
- Connect a test shopper through your connect route, and check that they land on
returnTowithlink=connected. - Ask for one item. Check that the answer’s
walletslists the Vault and Stripe Link, in your order. - Tap Stripe Link, then Approve. Check that the step’s
approval_urlopens Stripe Link’s page, and approve there. - Check that
buy.awaitWallet()answers withstatusplacingororder_placed. - Ask again, tap Stripe Link, and decline in Stripe Link. Check that the reply says nothing was charged and the cart is still there.