Skip to main content
Your iPhone app opens the Vault page or the approval page in an in-app browser. The shopper saves a card or approves the payment with Face ID, and the page sends them straight back into your app at the link you chose, such as yourapp://approved. Your app never sends the shopper to Safari, and the shopper never has to find their way back. Pass one option, returnUrl, when you build the tool:
agentcard.ts
Every link the tool hands to sendLink from then on ends at yourapp://agentcard-done: the Vault link for a shopper who has no card yet, and the approval link for each purchase. 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 as yourapp://agentcard-done, to your sandbox credentials and 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. Your app’s own scheme works, and so does https. An http link works only on localhost, in sandbox. Agentcard refuses an unregistered link before it starts the purchase, and the call throws an AgentcardApiError with code: invalid_return_url:

​
Open the page in an in-app browser

Open each vault and approval link in SFSafariViewController or ASWebAuthenticationSession. Both run Safari, so the shopper’s passkey works there with Face ID or Touch ID. A WKWebView inside your app 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.
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. 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, and the chat moves on from those messages. card_added arrives once the card is saved, and order_placed once the order goes through, through listen or the webhook handler, as Adding a card and Approving a purchase show. Post each message’s text into the chat as it arrives.

​
Carry your own state through the Vault

Make the Vault link yourself when your app wants a value of its own back, such as the moment on screen the shopper was buying from:
vault.ts
state needs returnUrl. A state without one throws a TypeError, and no request is sent.

​
Check it in the sandbox

  1. Register yourapp://agentcard-done on your sandbox credentials.
  2. Build the tool with returnUrl, and send “two packs of AA batteries from Amazon” as a test shopper nobody connected.
  3. Open the vault link in SFSafariViewController, 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 opens yourapp://agentcard-done and the browser closes.
  4. Send a returnUrl you did not register. Check that the call throws invalid_return_url.
The sandbox stops before payment, so the approval page and its return open only with live credentials. Check them by buying one inexpensive item with your own card, as Approving a purchase describes.