Skip to main content
Your iPhone app opens the add-a-card page or the approval page in an in-app browser, a browser window that opens inside your app. The shopper saves a card in the Vault, Agentcard’s page where the shopper keeps their card and approves payments, or approves the payment with Face ID. The page then sends them straight back into your app at the link you chose, such as yourapp://agentcard-done, and the shopper never has to find their way back from Safari. Pass your app’s link once, and every add-a-card link and approval link Agentcard hands out from then on ends at it.
Pass returnUrl when you build the tool:
agentcard.ts
Every vault and approval link the tool hands to sendLink ends at yourapp://agentcard-done.
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, 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:
The call throws an AgentcardApiError with code: invalid_return_url and status: 400:
Register that exact link on the credentials the call used, and send the call again.

Open the page in an in-app browser

Open each add-a-card link and approval link in SFSafariViewController 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.
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 to yourapp://agentcard-done?state=moment-7.
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. Send a return link you did not register. Check that Agentcard refuses it with invalid_return_url.
  1. Build the tool with returnUrl, and send “two packs of AA batteries from Amazon” as a test shopper nobody connected.
  2. 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.
At a store Agentcard pays itself, the sandbox stops before payment, so check that approval page and its return with live credentials by buying one inexpensive item with your own card, as Approving a purchase shows.