KYC

KYC (Know Your Customer) verifies a user’s identity through Plaid Identity Verification during installment-loan onboarding. Callers reach these endpoints through the User Service. Sessions are stored as Identity Verification rows and finalized asynchronously by Plaid webhooks.

KYC Statuses

kyc_status Meaning Set by

active

Session created; user has not finished the in-app steps.

Session creation (Plaid’s initial status)

processing

User finished the in-app steps; awaiting Plaid’s decision.

Completed endpoint

pending_review

Manual review required.

Webhook

success

Verification passed.

Webhook

failed

Verification failed; a rejected loan application is created in the LOC Service.

Webhook

expired

Session expired before completion.

Webhook

canceled

Session canceled.

Webhook

Source: pkg/miner/kyc.go, pkg/api/kyc.go

Watchlist Statuses

watchlist_status Meaning Set by

processing

Screening in progress.

Session creation

cleared

No watchlist match.

Webhook

pending_review

Match requires manual review.

Webhook

rejected

Watchlist match.

Webhook

Source: pkg/miner/kyc.go

Steps

idv_steps records Plaid’s status string for each of accept_tos, verify_sms, kyc_check, documentary_verification, selfie_check, watchlist_screening, risk_check. Source: pkg/dynamo/identity_verification.go.

Session Flow

  1. POST /{user_id}/transactions/kyc creates a session at Plaid from the user’s name, address, phone, email, and template id (is_retry creates a retry session instead). A row is saved unless one already exists for the returned session id. 201.

  2. POST /{user_id}/transactions/kyc/link returns a Link token for the latest session’s template; 404 when the user has no session.

  3. The app runs the Plaid flow, then calls POST /{user_id}/transactions/kyc/completed. An active session becomes processing; any other status is returned unchanged. 404 when the user has no session.

  4. Plaid sends IDENTITY_VERIFICATION and SCREENING webhooks; the miner updates the row (Webhooks).

  5. GET /{user_id}/transactions/kyc returns the latest session; 404 when none.

POST /qa/{user_id}/transactions/kyc/create (test only) writes a row directly.

Webhooks

Handled by the miner before item lookup — Miner Routing.

Webhook Action

IDENTITY_VERIFICATION / STATUS_UPDATED

Fetch the session from Plaid; create or update the row (status, steps, watchlist id, timestamps). failed: create a rejected loan application in the LOC Service. Other statuses: logged.

SCREENING / STATUS_UPDATED

Fetch the watchlist screening from Plaid; find the row by watchlist id (GSI2); set watchlist_status. All outcomes are logged.

Source: pkg/miner/kyc.go