Stripe Identity User Verification: Sessions, Results and Retries

Verify the user in your application#

Stripe Identity lets a business request identity checks from its users. For a platform onboarding a contractor, the useful result is a verification session tied to the correct application user, with a clear next action when a check needs more input. Uploading a document is one step; your server must establish the result before granting the access that depends on it.

This guide covers integrating the Identity product. Your own Stripe account verification and connected-account onboarding are separate workflows. A successful Identity check does not by itself activate a connected account, establish a company’s beneficial ownership or authorize a payout. Consult Connect’s verification requirements for that account relationship and track those requirements separately.

Choose the check and the way users enter it#

Start with the reason you need identity verification and the data required for that decision. A document check evaluates government-issued ID and can require a matching selfie. An ID-number check has a different collection and validation path. Configure the supported check for the use case and jurisdictions rather than collecting every available field.

Verification flows provide reusable configuration for sessions created through an API, the Dashboard or a static link. Flow changes affect future verifications. If you need to gate an authenticated user’s access, define how the resulting session will be bound to that user; a shared link or completed browser screen is insufficient evidence on its own.

Explain the purpose, requested checks, data use and help route before the user starts. Stripe’s customer-explanation guidance distinguishes biometric consent from other verification data handling. Customize your notice to the checks actually enabled and include your own privacy policy. Avoid promising that every user must provide a selfie or that one check completes all compliance obligations.

Create and bind the session on the server#

Authenticate the application user before your server calls the VerificationSession creation API. Select the supported verification configuration and store the returned session ID against your internal verification case. Use an opaque internal reference in client_reference_id or metadata where appropriate; do not put identity-document numbers or other sensitive records there.

Keep a durable mapping between application user, verification purpose, configuration version and session ID. Decide whether a user already has an active case before creating another session. Use a creation idempotency key for that case, and protect the mapping with a uniqueness or concurrency control so double-clicks and two workers cannot start competing sessions.

Treat the client secret as a sensitive session credential. Deliver it only to the authenticated user authorized for that case, over TLS, and exclude it from application logs, analytics and URLs. Secret API keys remain on the server. The frontend can use the returned client secret to open the verification experience, or follow the supported session URL. Do not forward a complete server response containing unnecessary personal data.

Example: contractor user u_42 starts verification case identity_42_v1. The server stores its Stripe session ID before returning the credential. A second click finds that case rather than creating a new session. A different logged-in user cannot retrieve its credential or claim its result simply by submitting the session ID to your endpoint.

Let session status determine the next action#

The VerificationSession object exposes the session status, last_error and last_verification_report. Use the session to track progress; inspect the latest report when you need details of a processed attempt. The report and session serve different jobs, so an individual check’s result is not a replacement for the current session state.

Keep browser completion separate from server verification. A user may finish or close a modal before the server has processed the checks. Show a pending state and obtain the authoritative session result. Do not promise a fixed 24-hour account-review window for Identity: it is a different product and processing can vary.

Stripe’s outcome-handling guide documents verified and requires_input events. Verify the webhook signature against the raw request body before trusting an event. Persist and deduplicate the event, locate the server-owned session mapping and update the relevant user’s case. A forged callback must not grant access.

For repeated or late events, retrieve current session state when needed rather than letting an older notification overwrite a newer decision. Apply the access transition once. Record the session ID, observed status, event or retrieval reference and decision timestamp without copying raw identity images into routine logs.

Reuse the case when a user needs another attempt#

If the session requires_input after an attempt, use last_error to choose a useful next instruction. For document_expired, ask the user to submit a supported unexpired document through the verification experience. A generic “try again” message leaves the user guessing. Put a bounded retry policy and an accessible support route around repeated failures.

The session lifecycle guidance recommends reusing an interrupted session. Retrieve it to obtain the fresh URL or client secret needed for a new attempt. Your endpoint must enforce the same user authorization as creation. Do not create a new session on every refresh or ask support to assemble an offline folder of passport copies.

In the u_42 example, an expired document returns the case to requires_input with document_expired. The user supplies another supported document through the same case; a subsequent verified result can satisfy the configured identity requirement. Other onboarding conditions remain separate. If the session was canceled or redacted, do not present it as reusable.

A timeout while creating a session is also a recovery problem. Reuse the supported creation idempotency key and reconcile the case before starting a new one. Keep your own case record beyond provider key retention; an expired key is not proof that the original request created nothing. Distinguish user-requested reverification under a new policy from accidental duplicate session creation.

Access only the verification data you need#

Stripe’s results-access guide describes controlled Dashboard access and API access to verified outputs. Sensitive fields such as document numbers, dates of birth and images need the documented restricted-key permissions and expansions. Separate support’s ability to see status from permission to inspect the underlying document.

If status is enough for the decision, avoid downloading document images. Where an authorized review needs an image, follow Stripe’s short-lived FileLink approach; its document and selfie links must expire within 30 seconds. Audit access and exclude links and sensitive payloads from logs. Broadly accessible offline “document packs” increase exposure without improving session correlation.

Define retention by purpose and applicable obligations for any data your business stores. Keep the smallest useful decision record: user/case mapping, session ID, configured checks, status, decision time and any necessary review reason. A verification result is not a reason to retain every image or report indefinitely.

Track redaction as a separate process#

For an authorized deletion request, inventory your copies and the Stripe session separately. The redaction API is irreversible and asynchronous: redaction.status moves from processing to redacted, with an identity.verification_session.redacted event on completion. Stripe documents that this may take up to four days. Do not equate the successful request with completed deletion.

A session still processing must finish before redaction. Redaction replaces personal-data fields and erases session metadata; it does not automatically delete copies your business exported elsewhere. Keep the internal mapping needed to finish the request according to your lawful retention policy, then reconcile your own deletion jobs. Do not use a redacted session as a fresh verification credential or claim its retained status provides access to erased evidence.

Give users a clear contact for verification problems and privacy requests. Explain which business requested the check and what information your integration receives. Record the request’s scope, permitted retention and completion across systems rather than promising that one Stripe action erases every record held by every party.

Check the integration before enabling access#

Exercise session creation twice, interrupted collection, requires_input, successful verification, canceled sessions and redaction. Include a wrong-user attempt to retrieve credentials, a bad-signature event and a duplicate or late event. Confirm the case stays attached to the intended user, that only the required decision grants access, and that logs contain no client secrets or raw identity data.

Test-mode responses help verify application handling but do not prove live identity checks, country coverage or document acceptance. Confirm the supported live configuration and current account eligibility before rollout. Keep production access policy explicit: identity verification can be one condition among several, without turning its result into a blanket approval for payments or account compliance.