How sessions work
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.
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.
As soon as the user submits the session, the VerificationSession moves to processing. Most verification checks take a few minutes to process.
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.
If any of the verification checks fail (for example, due to 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’ll need to Retrieve the VerificationSession to get a fresh URL or client secret.
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 type | Description |
|---|---|
identity.verification_session.created | The session was created. |
identity.verification_session.processing | The user has successfully submitted their information, and verification checks have started processing. |
identity.verification_session.verified | Processing of all the verification checks have completed, and they’re all successfully verified. |
identity.verification_session.requires_input | Processing of all the verification checks have completed, and at least one of the checks failed. |
identity.verification_session.canceled | The session has been canceled and future submission attempts have been disabled. This event is sent when a session is canceled. |
identity.verification_session.redacted | The 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.