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.
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_
— At least one of the document or the selfie checks failed.input
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:
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_EzwBts9TzGhZyUMHKBsvLtXM", "object": "identity.verification_report", "type": "document", "verification_session": "vs_1Xc3HCHVz5z3rXC8MhtWxK5d", "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_pAi6hx5OVLAZGPo4eNCvtAZI", "file_GBWDv8DZ0MlyBKkTfV3GXqin"], "issued_date": { "day": 4, "month": 27, "year": 2021 }, "issuing_country": "US" }, "selfie": { "status": "verified", "error": null, "document": "file_ZFiZzREjIXCQutSbWmTnzMm6", "selfie": "file_AvX2k1WaUGy5ofmrXWkl7zUN", } }
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 theerror
hash for more information.
When the verification check fails, the error
field contains code
and reason
values to explain the verification failure. The error.
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 code | Description |
---|---|
document_ | The provided identity document has expired. |
document_ | Stripe couldn’t verify the provided identity document. See list of supported document types. |
document_ | The 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 code | Description |
---|---|
selfie_ | The provided identity document did not contain a picture of a face. |
selfie_ | The captured face image did not match with the document’s face. |
selfie_ | Stripe couldn’t verify the provided selfie. |
selfie_ | The captured face image was manipulated. |