# Verify your users’ identity documents
Create sessions and collect identity documents.
This guide explains how to use Stripe Identity to securely collect and verify identity documents.
Show a document upload modal inside your website. Here’s what you’ll do:
1. Add a verification button to your webpage that displays a document upload modal.
1. Display a confirmation page on identity document submission.
1. Handle verification results.
## Before you begin
1. [Set up your Stripe account and verify your business](https://dashboard.stripe.com/account/onboarding).
1. Fill out your [Stripe Identity application](https://dashboard.stripe.com/identity/application).
1. (Optional) Customize your brand settings on the [branding settings page](https://dashboard.stripe.com/settings/branding?tab=identity).
You can also start by cloning a [sample integration](https://github.com/stripe-samples/identity) from GitHub.
## Set up Stripe [Server-side]
First, [register](https://dashboard.stripe.com/register) for a Stripe account.
Then install the libraries for access to the Stripe API from your application:
#### Ruby
```bash
# Available as a gem
sudo gem install stripe
```
```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```
## Add a button to your website [Client-side]
Create a button on your website for starting the verification.
#### HTML + JS
### Add a button
Start by adding a verify button to your page:
```html
Verify your identity
```
### Add the Stripe.js library to your page
Add [Stripe.js](https://docs.stripe.com/payments/elements.md) to your page by including a script tag in your HTML document:
```html
Verify your identity
```
> Always load **Stripe.js** directly from `https://js.stripe.com`. You can’t include it in a bundle or self-host it.
### Initialize Stripe.js
Initialize Stripe.js with your publishable [API key](https://docs.stripe.com/keys.md) by passing the following JavaScript to your page:
```html
Verify your identity
```
#### React
### Add a button
Start by adding a verify button to your page:
```jsx
import React from 'react';
class VerifyButton extends React.Component {
render() {
return (
);
}
}
const App = () => {
return (
);
};
export default App;
```
### Install Stripe.js
Install the [Stripe.js ES Module](https://www.npmjs.com/package/@stripe/stripe-js):
```bash
npm install @stripe/stripe-js
```
> If you’re using Node.js on the server, you need to install both the [stripe](https://www.npmjs.com/package/stripe) and [@stripe/stripe-js](https://www.npmjs.com/package/@stripe/stripe-js) packages. `stripe` is used on the server-side to make requests to the Stripe API, whereas `@stripe/stripe-js` provides methods for including [Stripe.js](https://docs.stripe.com/js.md) in your client-side code.
### Initialize Stripe.js
Call `loadStripe` with your publishable [API key](https://docs.stripe.com/keys.md). It returns a Promise that resolves with the Stripe object as soon as Stripe.js loads.
```jsx
import React from 'react';import {loadStripe} from '@stripe/stripe-js';
class VerifyButton extends React.Component {constructor(props) {
super(props);
this.state = {};
}
async componentDidMount() {
this.setState({ stripe: await this.props.stripePromise });
}
render() {const { stripe } = this.state;
return (
);
}
}
// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
const App = () => {
return (
);
};
export default App;
```
## Show the document upload modal [Client-side] [Server-side]
Set up the new button to show a document upload modal. After clicking the button, your user can capture and upload a picture of their passport, driver’s license, or national ID.
The modal reduces development time and maintenance and allows you to collect identity documents as part of your existing flows. It also decreases the amount of private information you handle on your site, allows you to support users in a variety of platforms and languages, and allows you to customize the style to match your branding.
### Create a VerificationSession
A [VerificationSession](https://docs.stripe.com/api/identity/verification_sessions.md) is the programmatic representation of the verification. It contains details about the type of verification, such as what [check](https://docs.stripe.com/identity/verification-checks.md) to perform. You can [expand](https://docs.stripe.com/api/expanding_objects.md) the [verified outputs](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) field to see details of the data that was verified.
After successfully creating a `VerificationSession`, send the [client secret](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-client_secret) to the frontend to show the document upload modal.
You can use verification flows for re-usable configuration, which is passed to the [verification_flow](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-verification_flow) parameter. Read more in the [Verification flows guide](https://docs.stripe.com/identity/verification-flows.md).
You need a server-side endpoint to [create the VerificationSession](https://docs.stripe.com/api/identity/verification_sessions/create.md). Creating the `VerificationSession` server-side prevents malicious users from overriding verification options and incurring processing charges on your account. Add authentication to this endpoint by including a user reference in the session metadata or storing the session ID in your database.
#### Node.js
```javascript
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
const stripe = require('stripe')('<>');
// In the route handler for /create-verification-session:
// Authenticate your user.
// Create the session.
const verificationSession = await stripe.identity.verificationSessions.create({
type: 'document',
provided_details: {
email: 'user@example.com',
},
metadata: {
user_id: '{{USER_ID}}',
},
});
// Return only the client secret to the frontend.
const clientSecret = verificationSession.client_secret;
```
> The client secret lets your frontend collect sensitive verification information. It’s single-use and expires after 24 hours. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Send only the client secret to your frontend to avoid exposing verification configuration or results.
Test your endpoint by starting your web server (for example, `localhost:4242`) and sending a POST request with curl to create a VerificationSession:
```bash
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""
```
The response in your terminal looks like this:
```bash
HTTP/1.1 200 OK
Content-Type: application/json
{ id: "vs_QdfQQ6xfGNJR7ogV6", client_secret: "vs_QdfQQ6xfGNJR7ogV6_secret_live_..." }
```
### Add an event handler to the verify button
Now that you have a button and an endpoint to create a VerificationSession, modify the button to show the document upload modal when clicked. Add a call to [verifyIdentity](https://docs.stripe.com/js/identity/modal) using the client secret:
#### HTML + JS
```html
Verify your identity
```
#### React
```jsx
import React from 'react';
import {loadStripe} from '@stripe/stripe-js';
class VerifyButton extends React.Component {
constructor(props) {
super(props);
this.state = {};this.handleClick = this.handleClick.bind(this);
}
async componentDidMount() {
this.setState({ stripe: await this.props.stripePromise });
}
async handleClick(event) {
// Block native event handling.
event.preventDefault();
const { stripe } = this.state;
if (!stripe) {
// Stripe.js hasn't loaded yet. Make sure to disable
// the button until Stripe.js has loaded.
return;
}
// Call your backend to create the VerificationSession.
const response = await fetch('/create-verification-session', { method: 'POST' });
const session = await response.json();
// Show the verification modal.
const { error } = await stripe.verifyIdentity(session.client_secret);
if (error) {
console.log('[error]', error);
} else {
console.log('Verification submitted!');
}
}
render() {
const { stripe } = this.state;
return (
);
}
}
// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
const App = () => {
return (
);
};
export default App;
```
### Event error codes
| Error code | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consent_declined` | The user declined verification by Stripe. Check with your legal counsel to see if you have an obligation to offer an alternative, non-biometric means to verify, such as through a manual review. |
| `device_unsupported` | The verification requires a camera and the user is on a device without one. |
| `under_supported_age` | Stripe doesn’t verify users under the age of majority. |
| `phone_otp_declined` | The user is unable to verify the provided phone number. |
| `email_verification_declined` | The user is unable to verify the provided email address. |
### Test the upload modal
Test that the verify button shows a document upload modal:
- Click the verify button, which opens the Stripe document upload modal.
- Ensure no error messages are shown.
If your integration isn’t working:
1. Open the Network tab in your browser’s developer tools.
1. Click the verify button to see if it makes an XHR request to your server-side endpoint (`POST /create-verification-session`).
1. Verify that the request returns a 200 status.
1. Use `console.log(session)` inside your button click listener to confirm that it returns the correct data.
## Show a confirmation page [Client-side]
To provide a user-friendly experience, show a confirmation page after users successfully submit their identity document. Host the page on your site to let the user know that the verification is processing.
#### HTML + JS
Create a minimal confirmation page:
```html
Your document was submitted
Thanks for submitting your identity document.
We are processing your verification.
```
Next, update the button handler to redirect to this page:
```html
Verify your identity
```
#### React
Update the button handler to show a confirmation message:
```jsx
import React from 'react';
import {loadStripe} from '@stripe/stripe-js';
class VerifyButton extends React.Component {
constructor(props) {
super(props);this.state = { submitted: false };
this.handleClick = this.handleClick.bind(this);
}
async componentDidMount() {
this.setState({ stripe: await this.props.stripePromise });
}
async handleClick(event) {
// Block native event handling.
event.preventDefault();
const { stripe } = this.state;
if (!stripe) {
// Stripe.js hasn't loaded yet. Make sure to disable
// the button until Stripe.js has loaded.
return;
}
// Call your backend to create the VerificationSession.
const response = await fetch('/create-verification-session', { method: 'POST' });
const session = await response.json();
// Show the verification modal.
const { error } = await stripe.verifyIdentity(session.client_secret);
if (error) {
console.log('[error]', error.message);
} else {
console.log('Verification submitted!');this.setState({ submitted: true });
}
}
render() {const { stripe, submitted } = this.state;
if (submitted) {
return (
<>
Thanks for submitting your identity document
We are processing your verification.
);
}
return (
);
}
}
// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>');
const App = () => {
return (
);
};
export default App;
```
### Test the confirmation page
Test that your confirmation page works:
- Click your verify button.
- Submit the session by selecting a predefined test case.
- Confirm that the new confirmation page is shown.
- Test the entire flow for failure cases (such as declining consent or refusing camera permissions) and ensure your app handles them without any issues.
Next, find the verification in the Stripe Dashboard. Verification sessions appear in the Dashboard’s [list of VerificationSessions](https://dashboard.stripe.com/identity). Click a session to go to the Session details page. The summary section contains verification results, which you can use in your app.
## Handle verification events
[Document checks](https://docs.stripe.com/identity/verification-checks.md#document-availability) are typically completed as soon as the user redirects back to your site and you can retrieve the result from the API immediately. In some rare cases, the document verification isn’t ready yet and must continue asynchronously. In these cases, you’re notified through webhooks when the verification result is ready. After the processing completes, the VerificationSession status changes from `processing` to `verified`.
Stripe sends the following events when the session status changes:
| Event name | Description | Next steps |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [identity.verification_session.verified](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.verified) | Processing of all the [verification checks](https://docs.stripe.com/identity/verification-checks.md) have completed, and they’re all successfully verified. | Trigger relevant actions in your application. |
| [identity.verification_session.requires_input](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.requires_input) | Processing of all the [verification checks](https://docs.stripe.com/identity/verification-checks.md) have completed, and at least one of the checks failed. | Trigger relevant actions in your application and potentially allow your user to retry the verification. |
Use a [webhook handler](https://docs.stripe.com/identity/handle-verification-outcomes.md) to receive these events and automate actions like sending a confirmation email, updating the verification results in your database, or completing an onboarding step. You can also view [verification events in the Dashboard](https://dashboard.stripe.com/events?type=identity.%2A).
## Receive events and run business actions
### With code
Build a webhook handler to listen for events and build custom asynchronous verification flows. Test and debug your webhook integration locally with the Stripe CLI.
[Build a custom webhook](https://docs.stripe.com/identity/handle-verification-outcomes.md)
### Without code
Use the Dashboard to view all your verifications, inspect collected data, and understand verification failures.
[View your test verifications in the Dashboard](https://dashboard.stripe.com/test/identity/verification-sessions)
## See also
- [Handle verification outcomes](https://docs.stripe.com/identity/handle-verification-outcomes.md)
- [Learn about VerificationSessions](https://docs.stripe.com/identity/verification-sessions.md)
- [Learn about Stripe.js](https://docs.stripe.com/payments/elements.md)