Verification Session

A VerificationSession guides you through the process of collecting and verifying the identities of your users. It contains details about the type of verification, such as what verification check to perform. Only create one VerificationSession for each verification in your system.

A VerificationSession transitions through multiple statuses throughout its lifetime as it progresses through the verification flow. The VerificationSession contains the user’s verified data after verification checks are complete.

Related guide: The Verification Sessions API

Endpoints

POST/v1/identity/verification_sessions

POST/v1/identity/verification_sessions/:id

GET/v1/identity/verification_sessions/:id

GET/v1/identity/verification_sessions

POST/v1/identity/verification_sessions/:id/cancel

POST/v1/identity/verification_sessions/:id/redact

The VerificationSession object

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_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.

provided_detailsnullable objectExpandable
Details provided about the user being verified. These details may be shown to the user.

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

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.

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": "..."
}

Create a VerificationSession

Creates a VerificationSession object.

After the VerificationSession is created, display a verification modal using the session client_secret or send your users to the session’s url.

If your API key is in test mode, verification checks won’t actually process, though everything else will occur as if in live mode.

Parameters

client_reference_idstring
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.

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

optionsobject
A set of options for the session’s verification checks.

provided_detailsobject
Details provided about the user being verified. These details may be shown to the user.

return_urlstring
The URL that the user will be redirected to upon completing the verification flow.

typeenum
The type of verification check to be performed. You must provide a type if not passing verification_flow.
Possible enum values
document
Document check.
id_number
ID number check.

verification_flowstring
The ID of a Verification Flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.

Returns

Returns the created VerificationSession object

POST /v1/identity/verification_sessions

Server-side language

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d type=document

Response

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

Update a VerificationSession

Updates a VerificationSession object.

When the session status is requires_input, you can use this method to update the verification check and options.

Parameters

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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

optionsobject
A set of options for the session’s verification checks.

provided_detailsobject
Details provided about the user being verified. These details may be shown to the user.

typeenum
The type of verification check to be performed.
Possible enum values
document
Document check.
id_number
ID number check.

Returns

Returns the updated VerificationSession object

POST /v1/identity/verification_sessions/:id

Server-side language

curl https://api.stripe.com/v1/identity/verification_sessions/vs_1NuN9WLkdIwHu7ix597AR9uz \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d type=id_number

Response

{
  "id": "vs_1NuN9WLkdIwHu7ix597AR9uz",
  "object": "identity.verification_session",
  "client_secret": "...",
  "created": 1695680478,
  "last_error": null,
  "last_verification_report": null,
  "livemode": false,
  "metadata": {},
  "options": {},
  "redaction": null,
  "status": "requires_input",
  "type": "id_number",
  "url": "..."
}

Retrieve a VerificationSession

Retrieves the details of a VerificationSession that was previously created.

When the session status is requires_input, you can use this method to retrieve a valid client_secret or url to allow re-submission.

Parameters

No parameters.

Returns

Returns a VerificationSession object

GET /v1/identity/verification_sessions/:id

Server-side language

curl https://api.stripe.com/v1/identity/verification_sessions/vs_1NuNAILkdIwHu7ixh7OtGMLw \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "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": "..."
}

Verification Session

The VerificationSession object

Attributes

idstring

objectstring

client_reference_idnullable string

client_secretnullable string

createdtimestamp

last_errornullable object

last_verification_reportnullable stringExpandable

livemodeboolean

metadataobject

optionsnullable object

provided_detailsnullable objectExpandable

redactionnullable object

statusenum

typeenum

urlnullable string

verification_flownullable string

verified_outputsnullable objectExpandable

Create a VerificationSession

Parameters

client_reference_idstring

metadataobject

optionsobject

provided_detailsobject

return_urlstring

typeenum

verification_flowstring

Returns

Update a VerificationSession

Parameters

metadataobject

optionsobject

provided_detailsobject

typeenum

Returns

Retrieve a VerificationSession

Parameters

Returns