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
Overview
Fraud detection
Stripe data
Financial reports
Payment authentication reports
Revenue recognition
Startup incorporation
Climate
Identity
    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
    Go live
    Before going live
    Supported use cases
    Explaining Identity
Tax
Financial Connections
Account
Dashboard
Identity
·
HomeBusiness operationsIdentity

Adding selfie checks

Learn how to add face similarity checks to prevent fraudsters from using stolen documents.

While document checks provide a defense against the use of fraudulent identity documents, it’s possible for fraudsters to get access to legitimate stolen documents. To prevent this, Stripe Identity can perform selfie checks on your users.

Selfie checks look for distinguishing biological traits, such as face geometry, from a photo ID and a picture of your user’s face. Stripe then uses advanced machine learning algorithms to ensure the face pictures belong to the same person.

To add selfie checks to your application, first follow the guide to collect and verify identity documents.

Adding selfie checks to VerificationSessions

When creating a VerificationSession, use the options.document.require_matching_selfie parameter to enable selfie checks.

Command Line
curl https://api.stripe.com/v1/identity/verification_sessions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d type=document \ -d "options[document][require_matching_selfie]"=true

This configures the verification flow to require a photo ID and a face picture from your user.

Accessing selfie check results

After it’s submitted and processed, the VerificationSession status changes depending on the result of the checks:

  • verified — Both the document and selfie checks were successful. The session verified_outputs contains extracted information from the document.
  • requires_input — At least one of the document or the selfie checks failed.

To access the captured selfie and document images, you’ll need to retrieve the associated VerificationReport, you can do this by expanding the last_verification_report field in the session:

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_4eC39HqLyjWDarjtT1zdp7dc'
); const verificationSession = await stripe.identity.verificationSessions.retrieve( '{{SESSION_ID}}', { expand: ['last_verification_report'], } ); const verificationReport = verificationSession.last_verification_report;

The VerificationReport has document and selfie fields holding the results of the document and selfie checks. Here’s an example VerificationReport with successful document and selfie checks:

{ "id": "vr_sJK9NxRSc191hdpRb7Cyjul0", "object": "identity.verification_report", "type": "document", "verification_session": "vs_hyEEjyN6evue37MlvIlRdduT", "created": 1611776872, "livemode": true, "options": { "document": { "require_matching_selfie": true } }, "document": { "status": "verified", "error": null, "first_name": "Jenny", "last_name": "Rosen", "address": { "line1": "1234 Main St.", "city": "San Francisco", "state": "CA", "postal_code": "94111", "country": "US" }, "document_type": "id_card", "expiration_date": { "day": 17, "month": 7, "year": 2024 }, "files": ["file_7VfzdbJ8YGiOBXxrmcYousJv", "file_rQfYWUd7kvkPALVOZm06LgKf"], "issued_date": { "day": 4, "month": 27, "year": 2021 }, "issuing_country": "US" }, "selfie": { "status": "verified", "error": null, "document": "file_YF05GdukHgismUXAhXJ2JVpr", "selfie": "file_7TitW3rXDIggxsuvHkIF1xs1", } }

To access the collected document and face images, see Accessing verification results.

Understanding selfie check failures

The document and selfie VerificationReport fields contain the collected data as well as a status and error fields to help you understand whether the check is successful or not.

The status field tells you whether each check is successful or not. The possible values are:

  • verified - The verification check is successful and the collected data is verified.
  • unverified - The verification check failed. You can check the error hash for more information.

When the verification check fails, the error field contains code and reason values to explain the verification failure. The error.code field can be used to programmatically handle verification failures. The reason field contains a descriptive message explaining the failure reason and can be shown to your user.

Document check failures

Failure details are available in the report document.error field.

Error codeDescription
document_expiredThe provided identity document has expired.
document_unverified_otherStripe couldn’t verify the provided identity document. See list of supported document types.
document_type_not_supportedThe provided identity document isn’t one of the session’s allowed document types.

Selfie check failures

Failure details are available in the report selfie.error field.

Error codeDescription
selfie_document_missing_photoThe provided identity document did not contain a picture of a face.
selfie_face_mismatchThe captured face image did not match with the document’s face.
selfie_unverified_otherStripe couldn’t verify the provided selfie.
selfie_manipulatedThe captured face image was manipulated.

See also

  • Verify your users’ identity documents
  • The Verification Sessions API
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Adding selfie checks to VerificationSessions
Accessing selfie check results
Understanding selfie check failures
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 your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe 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.
$