Seller Onboarding Service Low-Level Design: Identity Verification, Bank Verification, and Approval Workflow

What Is a Seller Onboarding Service?

A seller onboarding service collects, validates, and approves the information required before a seller can transact on a marketplace. It orchestrates identity verification, bank account validation, compliance screening, and a tiered approval workflow that grants progressively higher selling limits as each verification milestone is completed. The design must handle asynchronous callbacks from external verification providers, enforce approval state machines, and maintain a complete audit trail for regulatory purposes.

Requirements

Functional

Collect personal or business identity documents and submit them to an identity verification provider.
Validate bank account details via micro-deposit verification or instant bank verification APIs.
Run compliance checks including sanctions screening and politically exposed person (PEP) lookups.
Progress sellers through approval tiers (BASIC, STANDARD, PREMIUM) each with different selling limits.
Notify sellers of status changes and required actions via email and in-app notifications.

Non-Functional

Identity verification callback handling under 500 ms end-to-end.
Approval state transitions are idempotent and replay-safe.
Full audit log of every state change, document submission, and external verification result retained for seven years.

Data Model

OnboardingApplication: application_id, seller_id, tier_target (BASIC, STANDARD, PREMIUM), status (STARTED, IDENTITY_PENDING, IDENTITY_VERIFIED, BANK_PENDING, BANK_VERIFIED, COMPLIANCE_PENDING, COMPLIANCE_PASSED, REVIEW_QUEUE, APPROVED, REJECTED), current_tier (NONE, BASIC, STANDARD, PREMIUM), created_at, updated_at.
IdentityVerification: verification_id, application_id, provider, external_reference_id, document_type, status (SUBMITTED, PENDING, PASSED, FAILED, EXPIRED), result_json, submitted_at, completed_at.
BankVerification: bank_id, application_id, account_type (CHECKING, SAVINGS), routing_number_hash, account_number_hash, method (MICRO_DEPOSIT, INSTANT), status (PENDING, AWAITING_CONFIRMATION, VERIFIED, FAILED), initiated_at, verified_at.
ComplianceCheck: check_id, application_id, check_type (SANCTIONS, PEP, ADVERSE_MEDIA), provider, status (PENDING, CLEAR, HIT, ERROR), hit_details_json, checked_at.
AuditEvent: event_id, application_id, actor_type (SELLER, SYSTEM, REVIEWER), actor_id, event_type, before_status, after_status, metadata_json, occurred_at.

Core Algorithms

Identity Verification Flow

The seller uploads document images via a presigned URL to object storage. The onboarding service creates an IdentityVerification row, calls the identity provider API (e.g., Stripe Identity, Onfido) with a reference to the stored document, and receives a session token. The provider performs liveness and document checks asynchronously and posts a webhook callback with the result. The callback handler validates the HMAC signature, looks up the external_reference_id, updates the IdentityVerification row, and publishes an internal IDENTITY_RESULT event. An idempotency key on the callback prevents duplicate processing on provider retries.

Bank Verification

For micro-deposit verification: the service initiates two small deposits to the bank account via the payment provider and creates a BankVerification row in AWAITING_CONFIRMATION. The seller returns to confirm the deposit amounts; the service compares against stored expected amounts (hashed for PCI compliance) and updates status to VERIFIED on match. For instant bank verification: the seller authenticates with their bank via an OAuth flow through a provider (Plaid, MX), the service receives an access token, and calls the provider to confirm account ownership and retrieve routing details. Both paths write to the same BankVerification schema.

Tiered Approval Workflow

Each tier has a prerequisite checklist stored in configuration: BASIC requires identity verification only; STANDARD adds bank verification; PREMIUM adds compliance check and manual reviewer sign-off. The approval engine evaluates the checklist after each verification event. If all prerequisites for the target tier are met and no compliance hits are present, the application moves to APPROVED and current_tier is updated, unlocking the corresponding selling limits in the marketplace. Compliance hits route the application to REVIEW_QUEUE for a human analyst. The analyst can APPROVE (overriding the hit with a justification) or REJECT, both of which write audit events.

Scalability and Reliability

Webhook reliability: Incoming provider webhooks are written immediately to a raw_webhook table and acknowledged with HTTP 200. A separate processor reads the table, applies business logic, and marks the row processed. This decouples provider response time from internal processing time and survives database slowdowns without causing provider retries to fail.
State machine enforcement: Valid transitions are defined in code as a whitelist. Attempts to write an invalid transition are rejected before the database write, preventing corrupted state from external race conditions.
Document retention: Identity documents in object storage are tagged with a retention policy (seven years) enforced by bucket lifecycle rules. Document access is logged for compliance audit.
Compliance check caching: Sanctions and PEP check results for unchanged personal data are cached for 24 hours to avoid redundant provider calls on application resubmission.

API Design

POST /onboarding/applications — start an onboarding application for a seller; returns application_id.
POST /onboarding/applications/{id}/identity — submit identity document; returns presigned upload URL and verification session.
POST /onboarding/applications/{id}/bank — initiate bank verification; returns method-specific next-step instructions.
POST /onboarding/applications/{id}/bank/confirm — submit micro-deposit confirmation amounts.
GET /onboarding/applications/{id} — fetch application status, completed steps, and pending actions.
POST /webhooks/identity-provider — receive identity verification callbacks (HMAC-validated).
POST /onboarding/applications/{id}/review — reviewer endpoint to APPROVE or REJECT with justification.

Key Design Decisions

Writing raw webhooks before processing them decouples provider SLAs from internal processing reliability. Storing routing and account numbers as salted hashes rather than plaintext reduces PCI scope while still allowing deduplication checks to prevent the same bank account from being registered to multiple sellers. Encoding the tier prerequisite checklist in configuration rather than code lets compliance teams adjust requirements for new markets without deployments.

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “How is identity verification integrated into a seller onboarding flow?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “The seller submits a government-issued ID and a selfie. An IDV vendor (Persona, Jumio, Stripe Identity) performs document authenticity checks and a liveness/biometric match. The result (pass/fail/manual review) is returned via webhook and stored against the seller account. Failed or uncertain results route to a human review queue.”
}
},
{
“@type”: “Question”,
“name”: “How do you validate a seller's bank account during onboarding?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Two common approaches: micro-deposit verification (send two small amounts, seller confirms the values) and instant verification via Plaid or a bank OAuth flow. Instant verification is preferred for UX. The validated bank account token is stored with the payment processor (Stripe, Adyen) so the platform never directly handles account numbers.”
}
},
{
“@type”: “Question”,
“name”: “What does a tiered approval workflow look like for seller onboarding?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Tier 1 (low-risk) sellers pass automated IDV and bank validation and are approved immediately with capped transaction limits. Tier 2 sellers require additional business documentation and may have a manual review step with a 24-48 hour SLA. Tier 3 (high-volume or high-risk) sellers undergo full KYB (Know Your Business) review. Sellers are promoted between tiers based on transaction history and compliance status.”
}
},
{
“@type”: “Question”,
“name”: “What compliance checks are required in seller onboarding?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “At minimum: OFAC/sanctions list screening, PEP (Politically Exposed Person) checks, and AML (Anti-Money Laundering) risk scoring. For businesses: UBO (Ultimate Beneficial Owner) disclosure and KYB checks. Results are stored with audit timestamps. Ongoing monitoring re-screens sellers when watchlists are updated or when transaction patterns trigger a review.”
}
}
]
}