tessl/npm-stripe

Stripe API wrapper for Node.js providing comprehensive payment processing, subscription management, and financial services integration.

—

Pending

Overview

Eval results

Files

Identity

Name: tessl/npm-stripe
Author: tessl

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:

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:

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

// 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

// 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

// 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

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

Install with Tessl CLI