Verify your users’ identity documents (2024)

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:

Add a verification button to your webpage that displays a document upload modal.
Display a confirmation page on identity document submission.
Handle verification results.

Set up StripeServer-side

First, register for a Stripe account.

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

Command Line

Ruby

# Available as a gemsudo gem install stripe

Gemfile

Ruby

# If you use bundler, you can add this line to your Gemfilegem 'stripe'

Add a button to your websiteClient-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

Add the Stripe.js library to your page

Add Stripe.js to your page by including a script tag in your HTML document:

verification.html

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

Note

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 by passing the following JavaScript to your page:

verification.html

<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
); </script> </body></html>

Show the document upload modalClient-sideServer-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 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 client secret to the frontend to show the document upload modal.

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

Node

// Set your secret key. Remember to switch to your live secret key in production.// See your keys here: https://dashboard.stripe.com/apikeysconst stripe = require('stripe')(
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
);// 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: '[email protected]', }, metadata: { user_id: '{{USER_ID}}', },});// Return only the client secret to the frontend.const clientSecret = verificationSession.client_secret;

Caution

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:

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 OKContent-Type: application/json{ client_secret: "vs_QdfQQ6xfGNJR7ogV6..." }

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 using the client secret:

verification.html

<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
); 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) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the localized // error message to your user using `error.message`. if (result.error) { alert(result.error.message); } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body></html>

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:

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

Show a confirmation pageClient-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.

Create a minimal confirmation page:

submitted.html

<html> <head><title>Your document was submitted</title></head> <body> <h1>Thanks for submitting your identity document.</h1> <p> We are processing your verification. </p> </body></html>

Next, update the button handler to redirect to this page:

verification.html

<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
) 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) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the error message // using `error.message`. if (result.error) { alert(result.error.message); } else { window.location.href = 'submitted.html'; } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body></html>

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. Click a session to go to the Session Detail page. The summary section contains verification results, which you can use in your app.

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 name	Description	Next steps
identity.verification_session.verified	Processing of all the verification checks have completed, and they’re all successfully verified.	Trigger relevant actions in your application.
identity.verification_session.requires_input	Processing 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

FAQs

Verify your users’ identity documents? ›

In most cases, you'll need the original documents (for example, your passport, plastic driver licence, plastic Medicare card). In some cases, you may be able to use a NSW Photo Card as an identity document (check the transaction for details).

Read On ›

What documents do I need to confirm my identity? ›

Discover More Details ›

What is a document that confirms identity? ›

Identification card issued by the federal, state, or local government that contains a photograph. U.S. or foreign passport, U.S. passport card (expired passport may be used) or identification card issued by a foreign embassy or consulate that contains a photograph.

How to verify user identity? ›

Security questions: Users may be asked to answer security questions they are likely to know, such as their mother's maiden name or their high school. These carefully selected questions are examples of identity verification questions and are critical in help desk identity verification.

See Details ›

What are the ways to verify someone's identity? ›

Examples include a driver's license, a Social Security card, a valid passport, or military ID. Some organizations may accept a university ID or other non-government ID for one of them.

Find Out More ›

Which document is accepted as an identity proof? ›

Driving License. PAN Card. Post Office ID card. Bank Account Passbook/statement containing the photograph and signed by an individual with attestation by the concerned Bank official.

Tell Me More ›

What is a valid form of proof of identity? ›

A government issued ID

You can bring your driver's license, state issued ID or passport as proof of your identity.

Show Me More ›

What is an official document to verify your identity? ›

A large number of documents are highly suitable for document verification technology, including passports, driver's license, national ID cards, workplace ID or entry passes, permits, legal documents and bank cards.

Explore More ›

What are examples of identity documents? ›

Group 1 identity documents

current passport (any nationality)
Biometric Residence Permit (UK)
current driving licence photocard (full or provisional) (UK, Isle of Man, Channel Islands or Ireland)
birth certificate issued within 12 months of birth (UK, Isle of Man or Channel Islands)

More items...

Who can verify my identity? ›

The appropriate persons or bodies who are able to certify documents for this purpose are Solicitors (including a Notary Public), Chartered Accountant or a Doctor.

Show Me More ›

What are the three most common methods used to verify identity? ›

In the world of customer identity verification software, three methods stand out for their efficacy and widespread use: Document Verification, Biometric Verification, and Knowledge-Based Verification.

Read The Full Story ›

What is 3 the process of verifying the identity of a user? ›

The process of verifying the identity of a user is called Authentication.

See Details ›

How do you authenticate user identity? ›

Authentication factors include passwords, KBAs, biometric data, and physical tokens. These factors are matched within a database to prove that a user's identity is valid.

Get More Info Here ›

What do you write to confirm someone's identity? ›

Writing 'Certified to be a true copy of the original seen by me' on the document • Signing and dating it • Printing their name under the signature • Adding their occupation, address and telephone number • Adding an official stamp to the document.

What is using two methods to verify your identity known as? ›

Two-factor authentication (2FA) is an identity and access management security method that requires two forms of identification to access resources and data. 2FA gives businesses the ability to monitor and help safeguard their most vulnerable information and networks.

How is identity verification done? ›

Methods include facial verification, fingerprint matching, and comparing biometric data from verified sources to the person being checked. ID verification can be done online and offline, in person or remotely, depending on the circ*mstances.

View Details ›

What do I need to confirm my identity? ›

Requirements for identity verification

Your driver's license or state ID card. You can upload a photo of your ID by phone or by computer.
Social Security number.
Your phone number. In some cases, you can verify by mail instead.
Taking a photo of yourself.

What can you use to confirm your identity? ›

Need to prove your identity?

Passport.
Driving licence.
Recent utility bills.
Bank statements.

Learn More ›

What documents are proof of identity in the US? ›

U.S. or Indian Driver's License (with photo) U.S. Military ID. U.S. state ID (with photo) Alien Resident Card (“Green Card”) from U.S. CIS.

Discover More Details ›

What do I need to verify my identity with Social Security? ›

If you make a request to us in person, you must provide at least one piece of tangible identification such as a driver's license, passport, alien or voter registration card, or union card to verify your identity.

Show Me More ›

Verify your users’ identity documents (2024)

Add a button

Add the Stripe.js library to your page

Note

Initialize Stripe.js

Create a VerificationSession

Caution

Add an event handler to the verify button

Event error codes

Test the upload modal

Test the confirmation page

Receive events and run business actions

With code

Without code

See also

FAQs

Verify your users’ identity documents? ›

What are the three most common methods used to verify identity? ›