Skip to main content
POST
Create the session, then deliver 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.
string
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.
string
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.
string[]
["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.
string
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.
string
Connected sessions only, E.164. Used only when the account has no contact on file at all. Refused on open sessions.
number
Lifetime in seconds, 60 to 172800. Default 24 hours. Sessions are single use.
string
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.
string
Read the session by this id, never by the token inside url.
string
The link to send the user.
string | null
Null on an open session until it links.
number
Seconds to wait between reads if you poll.
Errors. 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