Skip to main content

Plaid Integration

Plaid is zkIdentity's KYC provider for the United States, United Kingdom, and the European Union. It provides financial identity verification by leveraging users' existing banking relationships. This document covers the integration architecture, verification flow, country coverage, and operational details.

Overview​

Plaid takes a fundamentally different approach to identity verification compared to document-based providers. Instead of asking users to upload identity documents, Plaid verifies identity through financial institutions where the user already has an established, verified relationship.

This approach offers several advantages:

  • No document uploads: Users do not need to photograph identity documents.
  • Pre-verified data: Banks have already verified their customers' identities.
  • Faster processing: Financial identity verification typically completes quickly.
  • Reduced friction: Users log in to their bank rather than handling physical documents.

zkIdentity uses Plaid's Identity Verification product, which combines bank-based identity data with optional document verification for cases where bank data alone is insufficient.

Integration Architecture​

User                  Frontend              Attestor (TEE)              Plaid
  |                      |                       |                        |
  |-- Select Plaid ----->|                       |                        |
  |                      |-- Create Session ----->|                        |
  |                      |                       |-- Create Link Token ---->|
  |                      |                       |<-- Link Token ----------|
  |                      |<-- Link Token ---------|                        |
  |                      |                        |                        |
  |   (Plaid Link opens in browser/embedded)      |                        |
  |-- Select Bank ------>|------------------------+----------------------->|
  |-- Login to Bank ---->|------------------------+----------------------->|
  |                      |                        |                        |
  |                      |         (Plaid verifies identity via bank)      |
  |                      |                        |                        |
  |                      |                        |<-- Webhook (result) ---|
  |                      |                        |-- zkFetch GET -------->|
  |                      |                        |<-- TLS response ------|
  |                      |                        |                        |
  |                      |          (generate 14 ZK proofs)                |
  |                      |                        |                        |
  |                      |<-- Status: verified ---|                        |
  |<-- Verified ---------|                        |                        |

Plaid Link is the client-side widget that handles the user's bank connection. It provides a secure, pre-built UI for:

  1. Institution selection: The user searches for and selects their bank.
  2. Authentication: The user enters their banking credentials directly into Plaid's secure widget. These credentials never pass through zkIdentity's systems.
  3. Multi-factor authentication: If the bank requires MFA, Plaid Link handles the MFA flow.
  4. Consent: The user reviews and approves the data sharing request.

The attestor creates a Link token for each verification session, which the frontend uses to initialize the widget.

Verification Products​

Identity Verification​

Plaid Identity Verification is the primary product used by zkIdentity. It can combine multiple verification steps including KYC checks against banking data, phone verification, document checks, selfie checks, and watchlist screening. The specific steps required are configured in the Plaid dashboard via verification templates.

Identity (Bank Data)​

As a supplementary product, Plaid can retrieve identity information directly from the user's bank account (legal name, date of birth, address, etc.). This data is used within the TEE for cross-referencing and is never stored or transmitted outside the enclave.

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.

Verification Result Handling​

Fields Extracted by Attestor (Non-PII Only)​

FieldPurpose
Verification statusDetermines verification outcome
Verification step resultsWhich steps passed/failed
TimestampWhen verification occurred
CountryDerived from user's bank location

Fields Never Extracted (PII)​

  • Date of birth
  • Name (given and family)
  • Address
  • Phone number
  • Email address
  • Bank account numbers, routing numbers
  • Bank login credentials (never available to zkIdentity)

Webhook Configuration​

Plaid sends webhook notifications for identity verification events. The attestor verifies webhook authenticity using JWT-based verification with Plaid's public key.

Error Handling​

Common Plaid error scenarios include:

  • User's bank is not supported
  • User's bank is experiencing an outage
  • Bank session expired during verification
  • Verification session not found or expired
  • API rate limit exceeded

The attestor handles these by recording the appropriate failure status and informing the user.

Plaid Sandbox Testing​

Plaid provides a comprehensive sandbox environment. Sandbox credentials are available immediately upon account creation. Plaid provides test usernames and passwords for simulating successful, failed, and MFA-required verification flows. Consult the Plaid sandbox documentation for current test credentials.