The VerificationSession object

Identity

Verification Session

Attributes

idstring
Unique identifier for the object.

objectstring
String representing the object’s type. Objects of the same type share the same value.

client_reference_idnullable string
A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.

client_secretnullable string
The short-lived client secret used by Stripe.js to show a verification modal inside your app. This client secret expires after 24 hours and can only be used once. 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. Refer to our docs on passing the client secret to the frontend to learn more.

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

last_errornullable object

If present, this property tells you the last error encountered when processing the verification.

last_error.codenullable enum

A short machine-readable string giving the reason for the verification or user-session failure.

Possible enum values

abandoned

The user began the verification but didn’t submit it.

consent_declined

The user declined to be verified 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.

country_not_supported

Stripe does not verify users from the provided country.

device_not_supported

The user’s device didn’t have a camera or they declined to grant Stripe permission to access it.

document_expired

The provided identity document has expired.

document_type_not_supported

The provided identity document isn’t one of the session’s allowed document types.

document_unverified_other

Stripe couldn’t verify the provided identity document. See list of supported document types.

email_unverified_other

Stripe was unable to verify the provided email address.

email_verification_declined

The user was unable to verify the provided email address.

id_number_insufficient_document_data

The provided document didn’t contain enough data to match against the ID number.

Show 9 more

last_error.reasonnullable string
A message that explains the reason for verification or user-session failure.

last_verification_reportnullable stringExpandable
ID of the most recent VerificationReport. Learn more about accessing detailed verification results.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

optionsnullable object
A set of options for the session’s verification checks.
- options.documentnullable object
  Options that apply to the document check.
  options.document.allowed_typesnullable array of enums
  Array of strings of allowed identity document types. If the provided identity document isn’t one of the allowed types, the verification check will fail with a document_type_not_allowed error code.
  Possible enum values
  driving_license
  Drivers license document type.
  id_card
  ID card document type.
  passport
  Passport document type.
  options.document.require_id_numbernullable boolean
  Collect an ID number and perform an ID number check with the document’s extracted name and date of birth.
  options.document.require_live_capturenullable boolean
  Disable image uploads, identity document images have to be captured using the device’s camera.
  options.document.require_matching_selfienullable boolean
  Capture a face image and perform a selfie check comparing a photo ID and a picture of your user’s face. Learn more.
- options.emailnullable object
  Options that apply to the email check.
  options.email.require_verificationnullable boolean
  Request one time password verification of provided_details.email.
- options.id_numbernullable object
  Options that apply to the id number check.
- options.matchingnullable object
  Options that apply to the matching check.
  options.matching.dobnullable enum
  Strictness of the DOB matching policy to apply.
  Possible enum values
  none
  No matching requirement.
  similar
  Fuzzy matching requirement.
  options.matching.namenullable enum
  Strictness of the name matching policy to apply.
  Possible enum values
  none
  No matching requirement.
  similar
  Fuzzy matching requirement.
- options.phonenullable object
  Options that apply to the phone check.
  options.phone.require_verificationnullable boolean
  Request one time password verification of provided_details.phone.

provided_detailsnullable objectExpandable
Details provided about the user being verified. These details may be shown to the user.
- provided_details.emailnullable string
  Email of user being verified
- provided_details.phonenullable string
  Phone number of user being verified

redactionnullable object

Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.

redaction.statusenum

Indicates whether this object and its related objects have been redacted or not.

Possible enum values

processing

This object has been redacted, and its related objects are in the process of being redacted. This process may take up to four days.

redacted

This object and its related objects have been redacted.

related_customernullable string
Customer ID

related_personnullable object
Tokens referencing the related Person resource and it’s associated account.
- related_person.accountstring
  Token referencing the associated Account of the related Person resource.
- related_person.personstring
  Token referencing the related Person resource.

statusenum

Status of this VerificationSession. Learn more about the lifecycle of sessions.

Possible enum values

canceled

The VerificationSession has been invalidated for future submission attempts.

processing

The session has been submitted and is being processed. Most verification checks are processed in less than 1 minute.

requires_input

Requires user input before processing can continue.

verified

Processing of all the verification checks are complete and successfully verified.

typeenum
The type of verification check to be performed.
Possible enum values
document
Document check.
id_number
ID number check.
verification_flow
Configuration provided by verification flow

urlnullable string
The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on verifying identity documents to learn how to redirect users to Stripe.

verification_flownullable string
The configuration token of a verification flow from the dashboard.

verified_outputsnullable objectExpandable

The user’s verified data.

verified_outputs.addressnullable object
The user’s verified address.
- verified_outputs.address.citynullable string
  City, district, suburb, town, or village.
- verified_outputs.address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
- verified_outputs.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
- verified_outputs.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
- verified_outputs.address.postal_codenullable string
  ZIP or postal code.
- verified_outputs.address.statenullable string
  State, county, province, or region.

verified_outputs.dobnullable objectExpandable
The user’s verified date of birth.
- verified_outputs.dob.daynullable integer
  Numerical day between 1 and 31.
- verified_outputs.dob.monthnullable integer
  Numerical month between 1 and 12.
- verified_outputs.dob.yearnullable integer
  The four-digit year.

verified_outputs.emailnullable string
The user’s verified email address

verified_outputs.first_namenullable string
The user’s verified first name.

verified_outputs.id_numbernullable stringExpandable
The user’s verified id number.

verified_outputs.id_number_typenullable enum

The user’s verified id number type.

Possible enum values

br_cpf

An individual CPF number from Brazil.

sg_nric

A national registration identity card number from Singapore.

us_ssn

A social security number from the United States. Only the last 4 digits are collected.

verified_outputs.last_namenullable string
The user’s verified last name.

verified_outputs.phonenullable string
The user’s verified phone number

verified_outputs.sexnullable enumExpandable
The user’s verified sex.
Possible enum values
[redacted]
The verification has been redacted.
female
Female
male
Male
unknown
Could not determine the user’s sex.

verified_outputs.unparsed_place_of_birthnullable stringExpandable
The user’s verified place of birth as it appears in the document.

verified_outputs.unparsed_sexnullable stringExpandable
The user’s verified sex as it appears in the document.

The VerificationSession object

{
  "id": "vs_1NuNAILkdIwHu7ixh7OtGMLw",
  "object": "identity.verification_session",
  "client_secret": "...",
  "created": 1695680526,
  "last_error": null,
  "last_verification_report": null,
  "livemode": false,
  "metadata": {},
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": null,
  "status": "requires_input",
  "type": "document",
  "url": "..."
}

The VerificationSession object

Attributes

idstring

objectstring

client_reference_idnullable string

client_secretnullable string

createdtimestamp

last_errornullable object

last_error.codenullable enum

last_error.reasonnullable string

last_verification_reportnullable stringExpandable

livemodeboolean

metadataobject

optionsnullable object

options.documentnullable object

options.document.allowed_typesnullable array of enums

options.document.require_id_numbernullable boolean

options.document.require_live_capturenullable boolean

options.document.require_matching_selfienullable boolean

options.emailnullable object

options.email.require_verificationnullable boolean

options.id_numbernullable object

options.matchingnullable object

options.matching.dobnullable enum

options.matching.namenullable enum

options.phonenullable object

options.phone.require_verificationnullable boolean

provided_detailsnullable objectExpandable

provided_details.emailnullable string

provided_details.phonenullable string

redactionnullable object

redaction.statusenum

related_customernullable string

related_personnullable object

related_person.accountstring

related_person.personstring

statusenum

typeenum

urlnullable string

verification_flownullable string

verified_outputsnullable objectExpandable

verified_outputs.addressnullable object

verified_outputs.address.citynullable string

verified_outputs.address.countrynullable string

verified_outputs.address.line1nullable string

verified_outputs.address.line2nullable string

verified_outputs.address.postal_codenullable string

verified_outputs.address.statenullable string

verified_outputs.dobnullable objectExpandable

verified_outputs.dob.daynullable integer

verified_outputs.dob.monthnullable integer

verified_outputs.dob.yearnullable integer

verified_outputs.emailnullable string

verified_outputs.first_namenullable string

verified_outputs.id_numbernullable stringExpandable

verified_outputs.id_number_typenullable enum

verified_outputs.last_namenullable string

verified_outputs.phonenullable string

verified_outputs.sexnullable enumExpandable

verified_outputs.unparsed_place_of_birthnullable stringExpandable

verified_outputs.unparsed_sexnullable stringExpandable