Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
OverviewExplore all products
Start building
Start developing
Sample projects
About the APIs
Building with LLMs
Use Stripe without code
Set up Stripe
Create an account
Products and prices
Web Dashboard
Mobile Dashboard
Migrate to Stripe
Migrate customer data
Migrate payment data
Migrate subscriptions
Manage fraud risk
Understand fraud
Radar fraud protection
Manage disputes
Verify identities
    Overview
    Get started
    Verify identity documents
    Handle verification outcomes
    Access verification results
    Review verification results
    Verification Flows
    More verification checks
    Verification checks
    Adding selfie checks
    About the APIs
    Verification Sessions
      How sessions work
    Go live
    Before going live
    Supported use cases
    Explaining Identity
Regulatory support
HomeGet startedVerify identitiesVerification Sessions

How sessions work

Learn about the status and lifecycle of VerificationSessions.

Copy page

Asynchronous verification flows are complex to manage because they depend on customer interactions that happen outside of your application. VerificationSessions simplify this by keeping track of the status of the verification flow.

requires_input

When the VerificationSession is created, it has a status of requires_input and is ready for your user to begin the verification process. We recommend creating the VerificationSession right before the start of the verification flow.

processing

As soon as the user submits the session, the VerificationSession moves to processing. Most verification checks are processed in less than 1 minute.

verified

A VerificationSession with a status of verified means that the verification flow is complete. Processing of all the verification checks are complete and successfully verified.

requires_input

If any of the verification checks fail (for example, because of a manipulated document), the VerificationSession’s status returns to requires_input. You can find an explanation for the verification failure in the last_error field of the session. If you want your user to attempt verification again, you need to Retrieve the VerificationSession to get a fresh URL or client secret. Details provided by the provided_details field might be shown to your user.

canceled

You may cancel a VerificationSession at any point before it’s processing or verified. This invalidates the VerificationSession for future submission attempts, and can’t be undone.

Session events

Events are created every time a session changes status. Here’s a complete list of the VerificationSession event types:

Event typeDescription
identity.verification_session.createdThe session was created.
identity.verification_session.processingThe user has successfully submitted their information, and verification checks have started processing.
identity.verification_session.verifiedProcessing of all the verification checks have completed, and they’re all successfully verified.
identity.verification_session.requires_inputProcessing of all the verification checks have completed, and at least one of the checks failed.
identity.verification_session.canceledThe session has been canceled and future submission attempts have been disabled. This event is sent when a session is canceled or redacted.
identity.verification_session.redactedThe session was redacted. You must create a webhook endpoint which explicitly subscribes to this event type to access it. Webhook endpoints which subscribe to all events will not include this event type.

You might want to take action in response to certain events, such as emailing your user when a verification fails or succeeds.

Stripe recommends that you listen for events with webhooks.

See also

  • The Verification Sessions API
  • Handle verification outcomes
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc