Skip to main content

Provider Setup

This document walks through the setup process for each KYC provider supported by zkIdentity. Each provider requires account creation, API credential configuration, webhook setup, and verification flow testing.

Smile ID Setup​

Account Registration​

  1. Visit smileidentity.com and request a developer account.
  2. Complete the business verification process (required for production access).
  3. Once approved, log in to the Smile ID dashboard.

API Credentials​

From the Smile ID dashboard, obtain:

  • Partner ID: Your account identifier.
  • API Key: Used for API authentication.
  • Signature Key: Used to sign and verify webhook payloads.

Configure these in your attestor environment variables, along with the environment setting (sandbox or production).

Webhook Configuration​

Smile ID sends verification results to your attestor via webhooks. Configure the webhook URL in the Smile ID dashboard:

  1. Navigate to the webhooks section in your Smile ID settings.
  2. Set the webhook URL to your attestor's webhook endpoint.
  3. Enable relevant webhook events for verification completion.
  4. Set the webhook signing secret to match your attestor's webhook secret.

Smile ID Verification Types​

zkIdentity leverages the following Smile ID verification products:

ProductDescription
Enhanced KYCDatabase lookup against government registries
Document VerificationID document image analysis and validation
Biometric KYCDocument verification + selfie match

The attestor selects the appropriate product based on the user's country and document type.

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, and Ethiopia (among others).

Coverage is continuously expanding. Check the Smile ID documentation for the most current list of supported countries and document types.

Smile ID Sandbox Testing​

Smile ID provides a sandbox environment for testing:

  • Sandbox credentials are separate from production credentials.
  • The sandbox accepts test document numbers to simulate various outcomes (success, failure, pending).
  • Consult the Smile ID sandbox documentation for current test values.

Plaid Setup​

Account Registration​

  1. Visit dashboard.plaid.com/signup and create a developer account.
  2. Complete the account verification process.
  3. For production access, submit a production application describing your use case.

API Credentials​

From the Plaid dashboard, obtain:

  • Client ID: Your Plaid client identifier.
  • Secret: Environment-specific secret key (sandbox, development, or production).

Configure these in your attestor environment variables.

Plaid Products​

zkIdentity uses the following Plaid products:

ProductDescription
Identity VerificationDocument + selfie verification for supported regions
IdentityBank account holder identity data for financial verification

Webhook Configuration​

Plaid sends verification events to your attestor via webhooks:

  1. In the Plaid dashboard, configure the webhook URL to your attestor's Plaid webhook endpoint.
  2. Plaid uses JWT-based webhook verification. The attestor verifies webhook signatures using the Plaid client library's built-in verification.

Plaid uses Plaid Link as the client-side widget for user interaction. The attestor creates a Link token for each verification session, which the frontend uses to initialize the widget. No additional frontend Plaid SDK configuration is needed beyond providing the Link token.

Supported Countries​

Plaid supports identity verification in the US, UK, and EU countries. Consult the Plaid documentation for the most current list of supported countries and institutions.

Plaid Sandbox Testing​

Plaid provides comprehensive sandbox testing:

  • Sandbox credentials are available immediately upon account creation.
  • Plaid provides test usernames and passwords for simulating various outcomes.
  • Consult the Plaid sandbox documentation for current test credentials.

Adding Both Providers​

For maximum geographic coverage, configure both providers simultaneously. The frontend will display available providers based on the user's selected country:

RegionPrimary Provider
Africa (Nigeria, Kenya, South Africa, Ghana, etc.)Smile ID
United States, UK, EUPlaid

Webhook Security​

Both providers support webhook signature verification to ensure webhook payloads are authentic:

  • Smile ID: Uses HMAC-based signature verification.
  • Plaid: Uses JWT-based webhook verification.

Both providers retry failed webhook deliveries. The attestor should acknowledge webhook receipt promptly. Processing happens asynchronously after acknowledgment.