Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

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.

Before you begin

  1. Activate your account.
  2. Fill out your Stripe Identity application.
  3. (Optional) Customize your brand settings on the branding settings page.

 

Send your users to Stripe to upload their identity documents. Here’s what you’ll do:

  1. Add a verification button to your webpage that redirects to Stripe Identity.
  2. Display a confirmation page on identity document submission.
  3. Handle verification results.

Set up Stripe
Server-side

First, register for a Stripe account.

Then install the libraries for access to the Stripe API from your application:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# 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.

Add a button

Start by adding a verify button to your page:

verification.html
<html>
  <head>
    <title>Verify your identity</title>
  </head>
  <body>
    <button id="verify-button">Verify</button>
  </body>
</html>

Redirect to Stripe Identity
Client-side
Server-side

Set up the button to redirect to Stripe Identity. After clicking the button, your frontend redirects to a Stripe-hosted page where they can capture and upload a picture of their passport, driver’s license, or national ID.

The redirect to Stripe Identity cuts down on development time and maintenance and gives you added security. 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 is the programmatic representation of the verification. It contains details about the type of verification, such as what check to perform. You can expand the verified outputs field to see details of the data that was verified.

After successfully creating a VerificationSession, send the session URL to the frontend to redirect to Stripe Identity.

You need a server-side endpoint to create the VerificationSession. 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.

server.js
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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 session URL to the frontend.
const url = verificationSession.url;

Caution

The session URL is single-use and expires after 48 hours. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Send only the session URL 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:

Command Line
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""

The response in your terminal looks like this:

Command Line
HTTP/1.1 200 OK
Content-Type: application/json

{ id: "vs_QdfQQ6xfGNJR7ogV6", url: "https://verify.stripe.com/start/QdfQQ6xfxNJR7ogV6Z6Wp..." }

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 redirect to the session URL when clicked:

verification.html
<html>
  <head>
    <title>Verify your identity</title>
    <script src="https://js.stripe.com/basil/stripe.js"></script>
  </head>
  <body>
    <button id="verify-button">Verify</button>

    <script type="text/javascript">
      var verifyButton = document.getElementById('verify-button');

      verifyButton.addEventListener('click', function() {
        // Get the VerificationSession client secret using the server-side
        // endpoint you created in step 3.
        fetch('/create-verification-session', {
          method: 'POST',
        })
        .then(function(response) {
          return response.json();
        })
        .then(function(session) {
          // When the user clicks on the button, redirect to the session URL.
          window.location.href = session.url;
        })
        .catch(function(error) {
          console.error('Error:', error);
        });
      });
    </script>
  </body>
</html>

Test the redirect

Test that the verify button redirects to Stripe Identity:

  • Click the verify button.
  • Ensure your browser redirects to Stripe Identity.

If your integration isn’t working:

  1. Open the Network tab in your browser’s developer tools.
  2. Click the verify button to see if it makes an XHR request to your server-side endpoint (POST /create-verification-session).
  3. Verify that the request returns a 200 status.
  4. Use console.log(session) inside your button click listener to confirm that it returns the correct data.

Handle verification events

Document checks 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 nameDescriptionNext steps
identity.verification_session.verifiedProcessing of all the verification checks have completed, and they’re all successfully verified.Trigger relevant actions in your application.
identity.verification_session.requires_inputProcessing of all the verification checks 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 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.

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

Without code

Use the Dashboard to view all your verifications, inspect collected data, and understand verification failures.

View your test verifications in the Dashboard

See also

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
Products Used
Identity