Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Get started
Verify identity documents
Handle verification outcomes
Access verification results
Review verification results
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
Identity
·
HomeBusiness operationsIdentityVerification Sessions

How sessions work

Learn about the status and lifecycle of VerificationSessions.

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.

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?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Session events
See also
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$