# Identity

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.

## Identity Verification

### Identity.VerificationSessions

Create and manage identity verification sessions:

```typescript { .api }
interface VerificationSession {
  id: string;
  object: 'identity.verification_session';
  status: 'requires_input' | 'processing' | 'verified' | 'canceled';
  type: 'document' | 'id_number';
  client_secret?: string;
  created: number;
  expires: number;
  last_error?: {
    code: string;
    reason: string;
  };
  last_verification_report?: string;
  metadata: Record<string, string>;
  options: {
    document?: {
      allowed_types: Array<'driving_license' | 'id_card' | 'passport'>;
      require_id_number: boolean;
      require_live_capture: boolean;
      require_matching_selfie: boolean;
    };
    id_number?: {
      // ID number verification options
    };
  };
  redaction?: {
    status: 'processing' | 'redacted';
  };
  related_customer?: string;
  url?: string;
  verified_outputs?: {
    address?: {
      city?: string;
      country?: string;
      line1?: string;
      line2?: string;
      postal_code?: string;
      state?: string;
    };
    dob?: {
      day?: number;
      month?: number;
      year?: number;
    };
    first_name?: string;
    id_number?: string;
    id_number_type?: 'br_cpf' | 'sg_nric' | 'us_ssn';
    last_name?: string;
  };
}

// Create document verification session
const session = await stripe.identity.verificationSessions.create({
  type: 'document',
  options: {
    document: {
      allowed_types: ['driving_license', 'passport', 'id_card'],
      require_id_number: true,
      require_live_capture: true,
      require_matching_selfie: true
    }
  },
  return_url: 'https://example.com/verify/return'
});

// Create verification for existing customer
const customerSession = await stripe.identity.verificationSessions.create({
  type: 'document',
  related_customer: 'cus_123',
  options: {
    document: {
      allowed_types: ['passport'],
      require_matching_selfie: true
    }
  },
  metadata: {
    purpose: 'account_onboarding',
    user_id: 'user_456'
  },
  return_url: 'https://example.com/onboarding/complete'
});

// Create ID number verification
const idSession = await stripe.identity.verificationSessions.create({
  type: 'id_number',
  options: {
    id_number: {
      // Configuration for ID number verification
    }
  },
  provided_details: {
    first_name: 'John',
    last_name: 'Doe',
    dob: {
      day: 1,
      month: 1,
      year: 1990
    },
    id_number: '123-45-6789'
  },
  return_url: 'https://example.com/verify/complete'
});

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

// Update session
const updated = await stripe.identity.verificationSessions.update('vs_123', {
  metadata: {
    internal_id: 'verification_789'
  }
});

// List sessions
const sessions = await stripe.identity.verificationSessions.list({
  status: 'verified',
  limit: 10
});

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

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

### Identity.VerificationReports

Access detailed verification reports and results:

```typescript { .api }
interface VerificationReport {
  id: string;
  object: 'identity.verification_report';
  created: number;
  document?: {
    address?: {
      city?: string;
      country?: string;
      line1?: string;
      line2?: string;
      postal_code?: string;
      state?: string;
    };
    dob?: {
      day?: number;
      month?: number;
      year?: number;
    };
    error?: {
      code: string;
      reason: string;
    };
    expiration_date?: {
      day?: number;
      month?: number;
      year?: number;
    };
    files?: Array<string>;
    first_name?: string;
    issued_date?: {
      day?: number;
      month?: number;
      year?: number;
    };
    issuing_country?: string;
    last_name?: string;
    number?: string;
    status: 'unverified' | 'verified';
    type?: 'driving_license' | 'id_card' | 'passport';
  };
  id_number?: {
    dob?: {
      day?: number;
      month?: number;
      year?: number;
    };
    error?: {
      code: string;
      reason: string;
    };
    first_name?: string;
    id_number?: string;
    id_number_type?: 'br_cpf' | 'sg_nric' | 'us_ssn';
    last_name?: string;
    status: 'unverified' | 'verified';
  };
  livemode: boolean;
  options: {
    document?: {
      allowed_types: Array<'driving_license' | 'id_card' | 'passport'>;
      require_id_number: boolean;
      require_live_capture: boolean;
      require_matching_selfie: boolean;
    };
    id_number?: Record<string, any>;
  };
  selfie?: {
    document?: string;
    error?: {
      code: string;
      reason: string;
    };
    selfie?: string;
    status: 'unverified' | 'verified';
  };
  type: 'document' | 'id_number';
  verification_session?: string;
}

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

// List verification reports
const reports = await stripe.identity.verificationReports.list({
  verification_session: 'vs_123',
  limit: 10
});
```

## Verification Flows

### Document Verification Flow

```typescript { .api }
// 1. Create verification session
const documentSession = await stripe.identity.verificationSessions.create({
  type: 'document',
  options: {
    document: {
      allowed_types: ['driving_license', 'passport'],
      require_id_number: true,
      require_live_capture: true,
      require_matching_selfie: true
    }
  },
  return_url: 'https://example.com/return/{VERIFICATION_SESSION_ID}'
});

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

// 3. Handle webhook after verification
app.post('/webhook', (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    endpointSecret
  );

  if (event.type === 'identity.verification_session.verified') {
    const session = event.data.object;
    
    // Access verification results
    const verifiedData = session.verified_outputs;
    console.log('Verified identity:', {
      name: `${verifiedData.first_name} ${verifiedData.last_name}`,
      dob: verifiedData.dob,
      address: verifiedData.address
    });
    
    // Update user status in your system
    updateUserVerificationStatus(session.related_customer, 'verified');
  }
  
  if (event.type === 'identity.verification_session.requires_input') {
    const session = event.data.object;
    // Handle cases where additional input is needed
    console.log('Verification requires input:', session.last_error);
  }
});
```

### Programmatic ID Verification

```typescript { .api }
// Create ID number verification
const idVerification = await stripe.identity.verificationSessions.create({
  type: 'id_number',
  provided_details: {
    first_name: 'Jane',
    last_name: 'Smith',
    dob: {
      day: 15,
      month: 6,
      year: 1985
    },
    id_number: '987-65-4321'
  },
  options: {
    id_number: {
      // Configuration specific to jurisdiction
    }
  }
});

// Check verification status
const status = idVerification.status; // 'processing', 'verified', etc.
```

## Advanced Usage

### Customer Onboarding Integration

```typescript { .api }
// Create customer with pending verification
const customer = await stripe.customers.create({
  email: 'customer@example.com',
  metadata: {
    verification_status: 'pending'
  }
});

// Create verification session for customer
const verificationSession = await stripe.identity.verificationSessions.create({
  type: 'document',
  related_customer: customer.id,
  options: {
    document: {
      allowed_types: ['passport', 'driving_license'],
      require_matching_selfie: true
    }
  },
  return_url: `https://example.com/onboard/complete?customer=${customer.id}`
});

// Update customer after verification
async function handleVerificationComplete(sessionId: string) {
  const session = await stripe.identity.verificationSessions.retrieve(sessionId);
  
  if (session.status === 'verified' && session.related_customer) {
    await stripe.customers.update(session.related_customer, {
      metadata: {
        verification_status: 'verified',
        verification_session: sessionId
      }
    });
  }
}
```

### Compliance and Data Management

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

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

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

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.