Vault sessions
Create a vault session
Create a single-use link the user opens to store a card behind their passkey.
POST
Create the session, then deliver
Errors.
url to the user in the thread or app you already share with them. One link is one enrollment: send it to one person and bind the user_id you receive to them. Send the URL exactly as returned, alone on its line: the token is signed, and a link with anything appended fails verification and opens the Vault’s sign-in page instead of the card form.
Omit for a new user: the session is open, the user is created at enrollment, and their id arrives in
vault.session_linked (or on the session read). Pass an id you already hold and the session is connected: opening the link sends a one-time code to the contact on that account and verifying it signs the user in.Your own id for the user, 1 to 128 characters. Echoed on
vault.session_linked and on the session read. On an open session for a user who already has a vault, the link asks for that user’s passkey and links to their existing user_id; it never sets up a second vault.["card"] opens the card form even when the user has a card on file: the link for adding another card. ["cards"] opens Your cards: the user sees the card you will pay with, keeps it or changes it, and leaves through the same “Back to” button, so send this one from inside a task rather than the card form. The session read answers card: true with the card_id they kept, as a plain link does.Where the page sends the user when they finish, such as
yourapp://vault-done. The last screen then shows one button, “Back to” followed by your app’s name, which opens this link. Without return_url, the button reads “Done” and opens the user’s cards. The link must be exactly one of the redirect URIs registered on the credentials that create the session: add it under Settings → Credentials → Redirect URIs in the dashboard, on your sandbox and production credentials alike. Your app’s own scheme works; http works only on localhost in sandbox.Connected sessions only, E.164. Used only when the account has no contact on file at all. Refused on open sessions.
partner asks the user to let your app pay with the card they save or pick, without an approval link for each purchase. customer leaves the choice to the user. Omit it to use your app’s default from Auto-approvals under Settings → Vault → Settings in the dashboard, which is customer until you change it. Only production client credentials can send partner: under sandbox credentials, partner is refused with 403 partner_enrollment_disabled. See Enable auto-approval.400 client_credentials_required (API key used), 422 contact_missing (connected session, nothing to send a code to), 400 invalid_return_url (return_url is not one of your registered redirect URIs), 403 partner_enrollment_disabled (app auto-approval isn’t available to this app in this mode: send approval_mode: "customer"), 429 rate_limited (open sessions are budgeted at 200 per organization per rolling 24 hours).
An unregistered return_url is refused with this body:
400