Smile ID Integration

Smile ID is zkIdentity's primary KYC provider for African countries. It provides document verification, biometric matching, and government database lookups across 12+ nations. This document covers the integration architecture, supported verification types, country coverage, and operational details.

Overview

Smile ID specializes in identity verification for Africa, where identity infrastructure varies significantly between countries. Their platform combines multiple verification methods:

• Government database lookups (Enhanced KYC): Direct verification against national identity registries.
• Document verification: AI-powered analysis of identity document images.
• Biometric verification: Selfie-to-document photo matching with liveness detection.

zkIdentity leverages Smile ID to enable privacy-preserving KYC for users across the continent, generating ZK proofs over Smile ID's verification results without exposing the underlying personal data.

Integration Architecture

User                   Frontend              Attestor (TEE)           Smile ID
  |                       |                       |                       |
  |-- Select Smile ID --->|                       |                       |
  |                       |-- Create Session ----->|                       |
  |                       |                       |-- Create Verification ->|
  |                       |                       |<-- Session Info --------|
  |                       |<-- Widget Config ------|                       |
  |-- Complete Widget --->|                       |                       |
  |                       |-------- (redirect to Smile ID widget) ------->|
  |                       |                       |                       |
  |                       |        (user uploads docs + selfie)           |
  |                       |                       |                       |
  |                       |                       |<-- Webhook (result) --|
  |                       |                       |-- zkFetch GET -------->|
  |                       |                       |<-- TLS response ------|
  |                       |                       |                       |
  |                       |          (generate 14 ZK proofs)              |
  |                       |                       |                       |
  |                       |<-- Status: verified --|                       |
  |<-- Verified ----------|                       |                       |

Supported Verification Products

Enhanced KYC

Enhanced KYC performs a direct lookup against government identity databases. This is the fastest verification method and does not require the user to upload documents.

How it works:

1. The user provides their ID number and basic information.
2. Smile ID queries the relevant government database.
3. The database returns a match/no-match result.

Advantages:

• Fast processing.
• No document or selfie required.
• High accuracy (direct government source).

Limitations:

• Only available in countries with accessible government databases.
• Requires the user to know their national ID number.

Document Verification

Document Verification uses AI to analyze photos of identity documents.

How it works:

1. The user takes a photo of their identity document.
2. Smile ID's AI extracts text and security features from the document image.
3. The system checks for signs of tampering, forgery, or expiration.

Biometric KYC

Biometric KYC combines document verification with selfie matching and liveness detection. This provides the highest assurance level by verifying both the document and that the person presenting it is the document holder.

Supported Countries

Smile ID supports identity verification in 12+ African countries, including:

• Nigeria, Kenya, South Africa, Ghana, Uganda, Tanzania, Rwanda, Cameroon, Senegal, Ivory Coast, DRC, Egypt, Ethiopia (among others)

note

Country and document coverage is continuously expanding. Check the Smile ID documentation for the most current list.

Verification Result Handling

When Smile ID completes a verification, it returns a structured result. The attestor processes this result within the TEE:

Fields Extracted by Attestor (Non-PII Only)

Field	Purpose
Verification status (result code)	Determines verification outcome
Country	Country of verification
Document type	Type of document used
Liveness check result	Whether liveness check passed
Session/job ID	Session correlation
Timestamp	When verification occurred

Fields Never Extracted (PII)

The following data exists in the Smile ID response but is never extracted, stored, or transmitted by the attestor:

• Date of birth
• Full legal name
• Document numbers (ID number, passport number)
• Photographs (base64 photo data)
• Residential address
• Any other personal data fields

Webhook Configuration

Smile ID sends webhook notifications as HTTP POST requests. The attestor verifies webhook authenticity using HMAC-based signature verification with the configured signature key.

Error Handling

Common Smile ID error scenarios include:

• Invalid ID number format
• ID number not found in government database
• Document image quality too low
• Face not detected in selfie
• Liveness check failed
• Country not supported

The attestor handles these by recording the appropriate failure status and informing the user of the issue so they can retry.

Related Documentation

• Provider Setup -- Configuring Smile ID credentials and webhooks.
• Plaid Integration -- Alternative provider for non-African regions.
• Custom Providers -- Adding new providers beyond Smile ID.
• Troubleshooting -- Resolving Smile ID specific issues.