Chapter 28: Vendor Onboarding and Verification

Why This Exists

A marketplace’s most valuable asset is trust. If buyers don't trust that they will receive what they ordered, they will never return. Because the platform does not own or ship the inventory, the only way to establish trust is to strictly control who is allowed to sell. Vendor Onboarding and Verification architecture exists to collect legal and financial identities, weed out fraudsters, and comply with strict international anti-money laundering (AML) laws.

Real World Problem

A scammer signs up for an open marketplace using a fake name and a prepaid debit card. They list 100 high-end laptops at 50% off. Eager buyers purchase them, generating $50,000 in sales over the weekend. The marketplace automatically pays the vendor on Monday. On Tuesday, buyers realize the laptops aren't coming and issue chargebacks. The scammer vanishes with the $50,000, and the marketplace must refund the buyers out of its own corporate bank account. The real-world problem is that anonymous selling enables massive financial fraud.

Everyday Analogy

Think of hiring a new employee. You don't just let a stranger walk into the office, sit at a desk, and start answering customer emails. First, you interview them. Then, you ask for their Driver's License and Social Security Number to run a background check. Finally, you ask for a voided check so you can set up direct deposit. Vendor onboarding is the automated, digital equivalent of the HR hiring process.

Beginner Explanation

Before someone can start selling on a marketplace, they have to prove they are a real person or a real business. They fill out a form with their name, address, and tax ID. They upload a picture of their passport. The computer checks this information against government databases. If everything looks good, the system asks for their bank account details so they can get paid. Until all this is done, the "Publish Product" button is locked.

Intermediate Explanation

In fintech and marketplace architecture, this process is known as KYC (Know Your Customer) for individuals, and KYB (Know Your Business) for companies.

Governments require platforms that move money to perform KYC to prevent money laundering and terrorist financing. The system must collect:

Legal Entity Name and Address.
Tax Identification Number (EIN in the US, VAT number in the EU).
Identifying details for the "Beneficial Owners" (anyone owning more than 25% of the company).

Because verifying this manually takes days, architectures integrate with specialized Identity Verification APIs (like Jumio, Onfido, or Stripe Identity).

Advanced Explanation

Architecturally, Vendor Onboarding is modeled as a State Machine. A vendor profile transitions through specific statuses based on webhook events from the KYC provider:

INCOMPLETE: Vendor just signed up.
PENDING_VERIFICATION: Documents uploaded, waiting for API response.
ACTION_REQUIRED: The API flagged the ID as blurry. The vendor must re-upload.
VERIFIED: The vendor is legally cleared to sell.
REJECTED: The vendor is on a global sanctions watchlist. Account permanently banned.

Furthermore, onboarding handles the Payment Routing Setup. The architecture must securely capture bank account details (Routing/Account numbers) and pass them to the payment gateway to create a "Connected Account" capable of receiving payouts.

Real World Example

Stripe Connect Onboarding: Building KYC infrastructure (document OCR, facial recognition, global watchlist screening) takes years. Modern marketplaces outsource this entirely using Stripe Connect. When a vendor clicks "Set up payments," they are redirected to a secure Stripe-hosted UI. Stripe collects their passport and bank details, performs the legal KYC checks, and then redirects the vendor back to the marketplace. Stripe sends a webhook to the marketplace backend saying, "Vendor 123 is now verified." The marketplace never touches the sensitive KYC data.

Architecture Design

Here is the flow of an automated KYC Onboarding process:

sequenceDiagram
    participant Vendor
    participant Marketplace_API
    participant KYC_Provider(Stripe)
    participant DB

    Vendor->>Marketplace_API: Click "Start Selling"
    Marketplace_API->>DB: Create Vendor (Status: PENDING)
    Marketplace_API-->>Vendor: Redirect to KYC Provider
    
    Note over Vendor,KYC_Provider(Stripe): Vendor uploads Passport & Bank Info
    
    KYC_Provider(Stripe)->>KYC_Provider(Stripe): Run OCR & Watchlist Checks
    
    KYC_Provider(Stripe)->>Marketplace_API: Webhook: account.updated (Verified)
    
    Marketplace_API->>DB: Update Vendor Status to VERIFIED
    Marketplace_API-->>Vendor: "You can now publish products!"

Database Design

Vendor Profile and KYC State:

CREATE TABLE vendors (
    id UUID PRIMARY KEY,
    user_id UUID,
    legal_business_name VARCHAR(255),
    tax_id_last_4 VARCHAR(4),
    kyc_status VARCHAR(50) DEFAULT 'INCOMPLETE', -- The State Machine
    gateway_account_id VARCHAR(100), -- E.g., Stripe Connect acct_123
    payout_bank_last_4 VARCHAR(4),
    created_at TIMESTAMP
);

API Design

Start Onboarding: POST /api/vendor/onboard/start (Returns a URL to redirect the user to the KYC provider's secure flow).

Webhook Receiver (From KYC Provider): POST /api/webhooks/kyc-updates (Listens for status changes and updates the kyc_status in the database).

Production Considerations

Friction vs. Conversion: The more information you ask for upfront, the fewer vendors will complete the sign-up process. To optimize conversion, use "Progressive Onboarding." Allow the vendor to set up their store and add products with just an email, but enforce the strict KYC/Passport upload only when they try to publish the store or accept their first payment.
Manual Review Queues: OCR (Optical Character Recognition) APIs fail if a picture is dark or blurry. The architecture must include an internal Admin Portal where human staff can manually review the flagged images and click "Approve" or "Reject."

Security Considerations

Toxic Data Liability: Passports, Driver's Licenses, and Social Security Numbers are "toxic data." If your database is breached and this data is stolen, the legal fallout is company-ending. Do not store images of passports in your own AWS S3 buckets. Pass them directly to the KYC provider and only store the non-sensitive metadata (like status: verified).

Common Mistakes

Letting Unverified Vendors Sell: Allowing a vendor to accept orders before their bank account is verified. If the verification ultimately fails, the platform is stuck holding money it cannot legally pay out, causing massive customer service headaches.
Ignoring Continuous Compliance: Assuming verification is a one-time event. If a previously verified vendor is later added to a government terror watchlist, the KYC provider will send an asynchronous webhook. If your system ignores it, you are facilitating illegal commerce.

Tradeoffs and Alternatives

Hosted UI vs. API Integration:
- Hosted UI (Stripe handles the screens): Zero frontend work, perfect compliance, but the user leaves your website briefly, which can feel disjointed.
- Custom API Integration: You build the forms and upload UI yourself. Perfectly branded experience, but you take on massive PCI/PII compliance liability and must build the error-handling logic yourself.

Interview Questions

What does KYC stand for, and why is it a legal requirement for marketplaces?
Explain why storing a vendor's passport image in your own database is a bad architectural decision.
Design a state machine for the vendor onboarding process. What are the key states?

Hands-On Exercise

Look up the "Stripe Connect Onboarding" documentation.
Read the difference between "Standard," "Express," and "Custom" connected accounts.
Note how the "Custom" tier requires you to build the UI yourself, while the others offload the UI to Stripe.

Key Takeaways

Marketplaces must establish trust and prevent fraud by rigorously verifying sellers.
KYC (Know Your Customer) is a legal requirement to prevent money laundering.
Onboarding is a State Machine that should be driven by asynchronous webhooks from third-party identity providers.
Never store raw KYC documents (passports, SSNs) on your own servers; offload the liability to specialized providers.