Skip to main content
Your iOS app presents the Vault’s links in a Safari view: the add-a-card page and the approval page open inside your app, and the user’s passkey works there.

Open the Vault in a Safari view

Create a vault session on your server, hand the url to the app, and present it with SFSafariViewController.
Use SFSafariViewController rather than WKWebView. The Vault saves the user’s card behind a passkey, and a Safari view shares Safari’s passkeys, so a returning user unlocks with Face ID inside your app. Inside a WKWebView the page cannot complete the passkey prompt and asks the user to open the link in Safari instead. Create the session on your server and hand the app only the url. Your client_secret never ships in the app binary. Open the approval link the same way. When your agent reaches the payment form, onApprovalUrl fires with a link; present it in the same Safari view, or send it by push notification if the user is not in the app. Once the user signs in or sets up their vault, you receive vault.session_linked with their user_id, and vault.card_stored when a card lands. Store the user_id: it is what you pass as user on every checkout. Without webhooks, poll the session instead.

Send the user back to your app

A card arriving does not mean the user is done: a returning user unlocks with their passkey, and may add a card or look at the ones they have. vault.session_linked fires at the unlock and vault.card_stored fires when a card lands, so neither is the moment to close the Safari view. Let the page tell you instead. Pass return_url when you create the session. The page then ends on a Card saved or Connected screen with one button, “Back to” followed by your app’s name, and tapping it opens your link.
Agentcard opens only a link registered on your credentials. Add the exact link, such as yourapp://vault-done, on your sandbox and production credentials alike. In the dashboard, open Settings → Credentials, choose Sandbox or Production, and add the link under Redirect URIs. Agentcard refuses an unregistered link when you create the session:
400
iOS opens the link in your app only when your app declares its scheme. In Xcode, open your target’s Info tab, add an entry under URL Types, and put your scheme, such as yourapp, under URL Schemes. When your app opens the link, dismiss the Safari view and ask your server to read the session:
The link arrives with nothing added, so read the result on your server with GET /api/v2/vault_sessions/{id}: status: linked and user_id say who connected, card_id names the card to pay with, whether the user saved it on this link or already had it, and last_step: left confirms the user tapped the button back to your app.

Open the user’s cards

A link you send from inside a task is a different errand from the first card: the user wants to see the card you will pay with and sometimes change it. Pass "steps": ["cards"] and the page ends on Your cards, with their saved cards listed, Add a card under them, and the same “Back to” button. The session read answers the same way, with card_id naming the card they kept.
A user with no card yet sees the card form first, and lands on Your cards once they save one. Keep the plain link, with no steps, for a user connecting for the first time, and ["card"] for a user you are sending straight to the form to add another.

Confirm with webhooks

The user dismissing the Safari view is a claim. Your server should act on webhooks, because the view can close before your app hears anything:
  • vault.card_stored when a card lands in the vault.
  • checkout_authorization.approved and the other checkout_authorization.* events when purchases are approved or declined.

Test it

A sandbox token creates a sandbox session. Present the link on your own device, store any of Stripe’s published test cards, any future expiry, any CVC. Rehearse a purchase against shop.agentcard.sh, a demo store on Stripe test mode. Next: Create a cart.