0
# Identity
1

2
Stripe Identity provides comprehensive identity verification services for KYC (Know Your Customer) and AML (Anti-Money Laundering) compliance. It supports document verification, biometric checks, and identity data collection with real-time verification results and fraud prevention capabilities.
3

4
## Identity Verification
5

6
### Identity.VerificationSessions
7

8
Create and manage identity verification sessions:
9

10
```typescript { .api }
11
interface VerificationSession {
12
  id: string;
13
  object: 'identity.verification_session';
14
  status: 'requires_input' | 'processing' | 'verified' | 'canceled';
15
  type: 'document' | 'id_number';
16
  client_secret?: string;
17
  created: number;
18
  expires: number;
19
  last_error?: {
20
    code: string;
21
    reason: string;
22
  };
23
  last_verification_report?: string;
24
  metadata: Record<string, string>;
25
  options: {
26
    document?: {
27
      allowed_types: Array<'driving_license' | 'id_card' | 'passport'>;
28
      require_id_number: boolean;
29
      require_live_capture: boolean;
30
      require_matching_selfie: boolean;
31
    };
32
    id_number?: {
33
      // ID number verification options
34
    };
35
  };
36
  redaction?: {
37
    status: 'processing' | 'redacted';
38
  };
39
  related_customer?: string;
40
  url?: string;
41
  verified_outputs?: {
42
    address?: {
43
      city?: string;
44
      country?: string;
45
      line1?: string;
46
      line2?: string;
47
      postal_code?: string;
48
      state?: string;
49
    };
50
    dob?: {
51
      day?: number;
52
      month?: number;
53
      year?: number;
54
    };
55
    first_name?: string;
56
    id_number?: string;
57
    id_number_type?: 'br_cpf' | 'sg_nric' | 'us_ssn';
58
    last_name?: string;
59
  };
60
}
61

62
// Create document verification session
63
const session = await stripe.identity.verificationSessions.create({
64
  type: 'document',
65
  options: {
66
    document: {
67
      allowed_types: ['driving_license', 'passport', 'id_card'],
68
      require_id_number: true,
69
      require_live_capture: true,
70
      require_matching_selfie: true
71
    }
72
  },
73
  return_url: 'https://example.com/verify/return'
74
});
75

76
// Create verification for existing customer
77
const customerSession = await stripe.identity.verificationSessions.create({
78
  type: 'document',
79
  related_customer: 'cus_123',
80
  options: {
81
    document: {
82
      allowed_types: ['passport'],
83
      require_matching_selfie: true
84
    }
85
  },
86
  metadata: {
87
    purpose: 'account_onboarding',
88
    user_id: 'user_456'
89
  },
90
  return_url: 'https://example.com/onboarding/complete'
91
});
92

93
// Create ID number verification
94
const idSession = await stripe.identity.verificationSessions.create({
95
  type: 'id_number',
96
  options: {
97
    id_number: {
98
      // Configuration for ID number verification
99
    }
100
  },
101
  provided_details: {
102
    first_name: 'John',
103
    last_name: 'Doe',
104
    dob: {
105
      day: 1,
106
      month: 1,
107
      year: 1990
108
    },
109
    id_number: '123-45-6789'
110
  },
111
  return_url: 'https://example.com/verify/complete'
112
});
113

114
// Retrieve session
115
const retrieved = await stripe.identity.verificationSessions.retrieve('vs_123');
116

117
// Update session
118
const updated = await stripe.identity.verificationSessions.update('vs_123', {
119
  metadata: {
120
    internal_id: 'verification_789'
121
  }
122
});
123

124
// List sessions
125
const sessions = await stripe.identity.verificationSessions.list({
126
  status: 'verified',
127
  limit: 10
128
});
129

130
// Cancel session
131
const canceled = await stripe.identity.verificationSessions.cancel('vs_123');
132

133
// Redact session (GDPR compliance)
134
const redacted = await stripe.identity.verificationSessions.redact('vs_123');
135
```
136

137
### Identity.VerificationReports
138

139
Access detailed verification reports and results:
140

141
```typescript { .api }
142
interface VerificationReport {
143
  id: string;
144
  object: 'identity.verification_report';
145
  created: number;
146
  document?: {
147
    address?: {
148
      city?: string;
149
      country?: string;
150
      line1?: string;
151
      line2?: string;
152
      postal_code?: string;
153
      state?: string;
154
    };
155
    dob?: {
156
      day?: number;
157
      month?: number;
158
      year?: number;
159
    };
160
    error?: {
161
      code: string;
162
      reason: string;
163
    };
164
    expiration_date?: {
165
      day?: number;
166
      month?: number;
167
      year?: number;
168
    };
169
    files?: Array<string>;
170
    first_name?: string;
171
    issued_date?: {
172
      day?: number;
173
      month?: number;
174
      year?: number;
175
    };
176
    issuing_country?: string;
177
    last_name?: string;
178
    number?: string;
179
    status: 'unverified' | 'verified';
180
    type?: 'driving_license' | 'id_card' | 'passport';
181
  };
182
  id_number?: {
183
    dob?: {
184
      day?: number;
185
      month?: number;
186
      year?: number;
187
    };
188
    error?: {
189
      code: string;
190
      reason: string;
191
    };
192
    first_name?: string;
193
    id_number?: string;
194
    id_number_type?: 'br_cpf' | 'sg_nric' | 'us_ssn';
195
    last_name?: string;
196
    status: 'unverified' | 'verified';
197
  };
198
  livemode: boolean;
199
  options: {
200
    document?: {
201
      allowed_types: Array<'driving_license' | 'id_card' | 'passport'>;
202
      require_id_number: boolean;
203
      require_live_capture: boolean;
204
      require_matching_selfie: boolean;
205
    };
206
    id_number?: Record<string, any>;
207
  };
208
  selfie?: {
209
    document?: string;
210
    error?: {
211
      code: string;
212
      reason: string;
213
    };
214
    selfie?: string;
215
    status: 'unverified' | 'verified';
216
  };
217
  type: 'document' | 'id_number';
218
  verification_session?: string;
219
}
220

221
// Retrieve verification report
222
const report = await stripe.identity.verificationReports.retrieve('vr_123');
223

224
// List verification reports
225
const reports = await stripe.identity.verificationReports.list({
226
  verification_session: 'vs_123',
227
  limit: 10
228
});
229
```
230

231
## Verification Flows
232

233
### Document Verification Flow
234

235
```typescript { .api }
236
// 1. Create verification session
237
const documentSession = await stripe.identity.verificationSessions.create({
238
  type: 'document',
239
  options: {
240
    document: {
241
      allowed_types: ['driving_license', 'passport'],
242
      require_id_number: true,
243
      require_live_capture: true,
244
      require_matching_selfie: true
245
    }
246
  },
247
  return_url: 'https://example.com/return/{VERIFICATION_SESSION_ID}'
248
});
249

250
// 2. Redirect user to verification URL
251
const verificationUrl = documentSession.url;
252

253
// 3. Handle webhook after verification
254
app.post('/webhook', (req, res) => {
255
  const event = stripe.webhooks.constructEvent(
256
    req.body,
257
    req.headers['stripe-signature'],
258
    endpointSecret
259
  );
260

261
  if (event.type === 'identity.verification_session.verified') {
262
    const session = event.data.object;
263
    
264
    // Access verification results
265
    const verifiedData = session.verified_outputs;
266
    console.log('Verified identity:', {
267
      name: `${verifiedData.first_name} ${verifiedData.last_name}`,
268
      dob: verifiedData.dob,
269
      address: verifiedData.address
270
    });
271
    
272
    // Update user status in your system
273
    updateUserVerificationStatus(session.related_customer, 'verified');
274
  }
275
  
276
  if (event.type === 'identity.verification_session.requires_input') {
277
    const session = event.data.object;
278
    // Handle cases where additional input is needed
279
    console.log('Verification requires input:', session.last_error);
280
  }
281
});
282
```
283

284
### Programmatic ID Verification
285

286
```typescript { .api }
287
// Create ID number verification
288
const idVerification = await stripe.identity.verificationSessions.create({
289
  type: 'id_number',
290
  provided_details: {
291
    first_name: 'Jane',
292
    last_name: 'Smith',
293
    dob: {
294
      day: 15,
295
      month: 6,
296
      year: 1985
297
    },
298
    id_number: '987-65-4321'
299
  },
300
  options: {
301
    id_number: {
302
      // Configuration specific to jurisdiction
303
    }
304
  }
305
});
306

307
// Check verification status
308
const status = idVerification.status; // 'processing', 'verified', etc.
309
```
310

311
## Advanced Usage
312

313
### Customer Onboarding Integration
314

315
```typescript { .api }
316
// Create customer with pending verification
317
const customer = await stripe.customers.create({
318
  email: 'customer@example.com',
319
  metadata: {
320
    verification_status: 'pending'
321
  }
322
});
323

324
// Create verification session for customer
325
const verificationSession = await stripe.identity.verificationSessions.create({
326
  type: 'document',
327
  related_customer: customer.id,
328
  options: {
329
    document: {
330
      allowed_types: ['passport', 'driving_license'],
331
      require_matching_selfie: true
332
    }
333
  },
334
  return_url: `https://example.com/onboard/complete?customer=${customer.id}`
335
});
336

337
// Update customer after verification
338
async function handleVerificationComplete(sessionId: string) {
339
  const session = await stripe.identity.verificationSessions.retrieve(sessionId);
340
  
341
  if (session.status === 'verified' && session.related_customer) {
342
    await stripe.customers.update(session.related_customer, {
343
      metadata: {
344
        verification_status: 'verified',
345
        verification_session: sessionId
346
      }
347
    });
348
  }
349
}
350
```
351

352
### Compliance and Data Management
353

354
```typescript { .api }
355
// Redact sensitive data for GDPR compliance
356
const redactedSession = await stripe.identity.verificationSessions.redact('vs_123');
357

358
// List all verifications for audit
359
const auditReport = await stripe.identity.verificationSessions.list({
360
  created: {
361
    gte: Math.floor(Date.now() / 1000) - (30 * 24 * 60 * 60) // Last 30 days
362
  },
363
  limit: 100
364
});
365

366
// Export verification data
367
auditReport.data.forEach(session => {
368
  console.log(`Session ${session.id}: ${session.status} - ${new Date(session.created * 1000)}`);
369
});
370
```
371

372
Stripe Identity provides a complete solution for regulatory compliance and fraud prevention through automated identity verification, supporting various document types and verification methods with detailed reporting and webhook integration for seamless workflow automation.