Skip to main content

Custom Providers

zkIdentity is designed to support multiple KYC providers beyond the built-in Smile ID and Plaid integrations. This document describes the general approach for integrating a new provider with the attestor.

Provider Interface​

Every KYC provider integration in zkIdentity must implement a common interface that ensures consistent behavior regardless of the underlying provider. The interface requires the following capabilities:

Required Capabilities​

A provider implementation must support:

  • Provider identification: A unique ID, display name, and list of supported countries.
  • Session creation: Creating a verification session with the provider's API and returning configuration the frontend needs to render the provider's UI.
  • Webhook processing: Parsing and validating webhook notifications from the provider.
  • Result fetching: Fetching the full verification result from the provider's API (this is the call that zkFetch will cryptographically prove via TLS tunnel).
  • Metadata extraction: Extracting only non-PII metadata from the provider's result (status, country, document type, liveness result, timestamp).
  • Webhook signature verification: Verifying the authenticity of incoming webhooks.
  • Health checking: Verifying connectivity to the provider's API.

Implementation Guide​

General Steps​

  1. Create the provider module in the attestor's providers directory.
  2. Implement the provider interface with all required methods.
  3. Register the provider in the provider registry so the attestor can discover it.
  4. Add configuration (environment variables for API keys, base URL, webhook secret, etc.).
  5. Update the frontend to include the new provider in the provider selection UI with its supported countries.

Metadata Extraction Rules​

The metadata extraction method is critical for privacy. It must only extract non-PII fields:

Allowed (non-PII):

  • Verification status
  • Provider identifier
  • Country code
  • Document type category
  • Liveness check result
  • Timestamp

Never extracted (PII):

  • Name, date of birth
  • Document numbers
  • Address, phone number
  • Photographs, biometric data
  • Financial account numbers

Webhook Requirements​

Custom providers must deliver webhook notifications to the attestor. Requirements:

  • HTTPS only: Webhooks must be delivered over HTTPS.
  • Signature verification: The provider must support some form of webhook signature verification (HMAC, JWT, or equivalent).
  • JSON payload: The webhook body must be JSON.
  • Idempotency: The attestor treats webhooks idempotently. Duplicate deliveries are handled gracefully.

zkFetch Compatibility​

For the ZK proof system to work with a custom provider, the provider's result API must meet these requirements:

  1. HTTPS endpoint: The result API must be served over HTTPS (TLS 1.2 or 1.3).
  2. JSON response: The result must be returned as JSON.
  3. Stable response format: The JSON structure must be predictable so that ZK circuits can extract specific fields.
  4. Authentication via headers: API authentication must be possible via HTTP headers.

Unsupported Provider Patterns​

The following patterns are not compatible with zkFetch:

  • GraphQL APIs: The variable query structure makes circuit design impractical.
  • Streaming responses: zkFetch requires a complete response.
  • Binary responses: Only JSON text responses are supported.
  • Client certificate authentication: Not supported in the TLS tunnel.

Testing Custom Providers​

Key Test Areas​

  • Session creation: Verify the provider integration can create sessions successfully.
  • Webhook signature verification: Test with valid and invalid signatures.
  • Non-PII metadata extraction: Verify only allowed fields are extracted (no PII leakage).
  • Integration test: End-to-end flow from session creation through proof generation using the provider's sandbox API.

Mock Provider for Development​

Create a mock implementation of the provider for local development that returns controlled responses for different test scenarios.

Provider Submission Checklist​

Before submitting a new provider integration for review:

  • Implements the complete provider interface
  • Webhook signature verification is implemented and tested
  • Only non-PII metadata is extracted (verified by tests)
  • Environment variables are documented
  • Supported countries list is accurate
  • Frontend provider configuration is added
  • Tests pass with provider's sandbox API
  • Mock provider is created for local development
  • zkFetch compatibility is confirmed (HTTPS, JSON, stable format)
  • Error handling covers known provider error codes