yourapp://agentcard-done, and the shopper never has to find their way back from Safari.
Set your return link
Pass your app’s link once, and every add-a-card link and approval link Agentcard hands out from then on ends at it.- SDK
- MCP
- API
Pass Every
returnUrl when you build the tool:agentcard.ts
vault and approval link the tool hands to sendLink ends at yourapp://agentcard-done.Register your app’s link
Agentcard sends a shopper only to a link your company registered, so a link copied into a request from anywhere else goes nowhere. Add the exact link, such asyourapp://agentcard-done, to your sandbox credentials, the ones for Agentcard’s test mode, which charges nothing, and to your production credentials alike.
In the dashboard, open Settings → Developers → Credentials, add the link under Redirect URIs on the Sandbox tab, then add it again on the Production tab. A link in your app’s own scheme, the prefix such as yourapp:// that opens your app, works, and so does https. An http link works only on localhost, in the sandbox.
Agentcard refuses a link you did not register before it starts the purchase, and nothing happens to the shopper’s cart:
- SDK
- MCP
- API
The call throws an
AgentcardApiError with code: invalid_return_url and status: 400:Open the page in an in-app browser
Open each add-a-card link and approval link inSFSafariViewController or ASWebAuthenticationSession. Both run Safari, so the shopper’s passkey, the fingerprint or face check that approves a payment, works there with Face ID or Touch ID.
A WKWebView, a web view your app draws itself, cannot use the shopper’s passkey. The page then shows the shopper a button that opens it in Safari instead, and the shopper returns to your app from there. Use one of the two Safari views to keep the shopper inside your app.
Open each URL exactly as Agentcard gave it. Send each link shows where each link appears.
- SDK
- MCP
- API
chat.ts
Read what the shopper did
The page sends the shopper to your link with what happened on it, so your app can close the browser and move on without asking Agentcard.authorization_id names the payment the shopper decided on. A registered link that already carries a query, such as yourapp://done?from=agentcard, comes back exactly as registered, with nothing added.
ASWebAuthenticationSession hands the link to its completion handler and closes on its own when you start it with your link’s scheme. With SFSafariViewController, your app’s link handler receives it, and your app dismisses the view.
Agentcard still tells your server what happened: a card_added message once the card is saved, and order_placed once the order goes through. Move the purchase on from those, as Move the purchase on shows.
Get your own value back
Make the add-a-card link yourself when your app wants a value of its own back, such as the screen the shopper was buying from. The shopper then returns toyourapp://agentcard-done?state=moment-7.
- SDK
- MCP
- API
vault.ts
state needs returnUrl. A state without one throws a TypeError, and no request is sent.Check it in the sandbox
- Register
yourapp://agentcard-doneon your sandbox credentials. - Send a return link you did not register. Check that Agentcard refuses it with
invalid_return_url.
- SDK
- MCP
- API
- Build the tool with
returnUrl, and send “two packs of AA batteries from Amazon” as a test shopper nobody connected. - Open the
vaultlink inSFSafariViewController, and save a test card with Face ID or Touch ID. A shopper nobody connected saves their card first, so the link asks for no code. Check that your app opensyourapp://agentcard-doneand the browser closes.