Access verification results

To build an integration with Stripe Identity that prioritises your user’s privacy, you must first decide the minimum amount of PII that you need access to. If you don’t need access to the most sensitive data (that requires authentication with a restricted API key), then your integration can authenticate using your secret key only.

To access PII resulting from a verification, you can retrieve a VerificationSession and expand either the verified_outputs field or – if you need more granular detail on the verification result – the last_verification_report. Expanding either of these fields automatically includes all of the PII fields they contain that only require a secret key.

Here is an example of how to expand the verified_outputs field to retrieve a user’s name that was verified by Stripe Identity.

// 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: [
      'verified_outputs',
    ],
  }
);

const firstName = verificationSession.verified_outputs.first_name;

If you do need to access sensitive PII that requires a restricted key, follow the steps in this guide.

You can use your account’s secret API keys to perform any API request without restriction. Accessing sensitive verification results requires restricted keys, which are more secure.

To create a new restricted key,

1. Go to the API keys page in the Dashboard and click Create restricted key.
2. Name your key.
3. Make sure the Identity Verification Sessions and Reports and Access recent sensitive verification results permissions are set to Read.
4. (optional) If you need to access collected images, add the Files Write permission.
5. Click Create key.
6. Store the key securely. Learn more about keeping your keys safe.

VerificationReports contain all the collected data and verification results from a submitted session. VerificationReports are created when all verification checks for a session are processed. They allow you to understand why a verification check failed and what data was successfully verified.

You can expand the last_verification_report session field to retrieve the associated VerificationReport.

By default, VerificationReports don’t include sensitive verification results. To access these, you’ll need to:

1. Authenticate using the restricted API key created in step 1.
2. Expand the fields you want to access.

Here’s an example of accessing the extracted date of birth, ID number, and document number from a document check:

// Set your restricted key. Remember to switch to a live restricted key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('rk_test_...');

const verificationSession = await stripe.identity.verificationSessions.retrieve(
  '{{SESSION_ID}}',
  {
    expand: [
      'verified_outputs.dob',
      'verified_outputs.id_number',
      'last_verification_report.document.number',
    ],
  }
);

const dateOfBirth = verificationSession.verified_outputs.dob;
const idNumber = verificationSession.verified_outputs.id_number;
const documentNumber = verificationSession.last_verification_report.document.number;

Accessing collected images

You can retrieve identity document and face images that you collect as part of a session using the File Upload API. The following fields on a VerificationReport can hold a reference to a File resource in the Stripe API:

• document.files – images of the identity document
• selfie.document – image of the photo ID front
• selfie.selfie – image of the user’s face

To access the contents of the file, you need to authenticate using the previously created restricted key and Create a FileLink with a short expiration and send the url to the client:

// Set your restricted key. Remember to switch to a live restricted key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('rk_test_...');

// Get the VerificationReport
const session = await stripe.identity.verificationSessions.retrieve(
  '{{SESSION_ID}}',
  {
    expand: ['last_verification_report'],
  }
);

// Retrieve the File id
const report = session.last_verification_report;
const documentFrontFile = report.document.files[0];

// Create a short-lived FileLink
const fileLink = await stripe.fileLinks.create({
  file: documentFrontFile,
  expires_at: Math.floor(Date.now() / 1000) + 30,  // link expires in 30 seconds
});

// Access the FileLink URL to download file contents
const fileUrl = fileLink.url;

If you believe an attacker has accessed sensitive data collected by Identity, please reach out to support.

Using restricted API keys that only have Identity permissions allows you to roll the keys in case of emergency without affecting other Stripe product integrations.

We recommend that you regularly monitor your restricted key usage to ensure that no one has gained access to them. In the Dashboard, you can use the overflow menu (…) to view request logs for a specific API key to view all the requests made from that key.

If an API key is compromised, roll the key in the Dashboard to block it and generate a new one. Make sure to expire it immediately to prevent bad actors from retrieving sensitive information.

If you believe an attacker has accessed sensitive data collected by Identity, please reach out to support.

Make sure your privacy policy includes information on your use of sensitive verification results. It may also help if you provide information about your security practices.

See also

• Privacy considerations for handling ID verification data as a business
• FAQs to provide to your users