marketplace-building

市场平台搭建

概述

多卖家市场平台允许独立卖家在你的平台上发布商品，向买家收款、扣除佣金，再将剩余款项支付给卖家。其关键组成部分包括：通过 KYC 验证引导卖家入驻、管理每位卖家发布的商品、计算佣金，以及自动付款。对于 Shopify 和 WooCommerce 商家，专门的市场平台应用可以处理大部分工作；只有在佣金结构高度特殊或需要搭建白标市场平台时，才主要需要定制开发。

何时使用此技能

• 搭建一个由第三方卖家发布并销售自有商品（而非你的库存商品）的平台时
• 需要由平台向买家收款，并在扣除佣金后向卖家分配资金时
• 卖家需要拥有自己的控制面板来管理商品、查看订单和追踪收入时
• 需要遵守 KYC（了解你的客户）要求以验证卖家身份时
• 设计佣金结构（按比例、分级或按类别）和付款计划时

核心说明

步骤 1：确定平台并选择合适的市场平台工具

平台	推荐工具	原因
Shopify	Webkul 的 Multi Vendor Marketplace 或 BOLD Multi-Vendor	Webkul 的应用可为 Shopify 添加卖家账户、商品管理、佣金规则和卖家控制面板，无需替换店面
WooCommerce	Dokan Multi-Vendor（最受欢迎，安装量超过 60K）或 WC Vendors	Dokan 专为 WooCommerce 市场平台打造，提供卖家入驻、佣金管理、付款申请和卖家控制面板
BigCommerce	Webkul 的 Multi Vendor Marketplace（BigCommerce 版本）	Webkul 提供其市场平台应用的 BigCommerce 版本
自定义 / 无头架构	构建卖家账户 + 使用 Stripe Connect 处理 KYC 和付款	Stripe Connect 可处理 KYC、银行账户信息收集和 1099-K 税表 — 任何自定义市场平台都应使用它

步骤 2：设置卖家入驻和 KYC

KYC（了解你的客户）要求在你合法向卖家付款前验证其身份。强烈建议使用 Stripe Connect 来处理这项工作 — 自行构建成本高昂，且法律流程复杂。

Shopify — Webkul 的 Multi Vendor Marketplace

1. 从 Shopify 应用商店安装 Webkul 的 Multi Vendor Marketplace
2. 卖家通过卖家注册表单注册（URL 可自定义，例如 yourstore.com/seller/register）
3. 你在 Webkul 管理后台手动审批卖家申请 — 审批前请检查卖家资料
4. 将 Webkul 连接到 Stripe Connect 以便付款：前往 Webkul → Settings → Payment → Stripe Connect，并输入你的 Stripe 凭据
5. 你批准卖家后，Webkul 会向其发送入驻邮件，其中包含连接 Stripe 账户的链接（Stripe Express 账户 — Stripe 负责 KYC 和银行账户信息）
6. 卖家的 Stripe Express 账户通过验证后即可上线（Stripe 会通过 webhook 通知你）

WooCommerce — Dokan Multi-Vendor

1. 从 WordPress.org（免费版）或 Dokan.com（专业版）安装 Dokan Multi-Vendor Plugin
2. 启用卖家注册：前往 Dokan → Settings → General → Allow Registration
3. 使用必填字段自定义卖家注册表单（企业名称、税号、银行信息）
4. 对于 KYC：Dokan Pro 集成了 Stripe Connect — 前往 Dokan → Settings → Withdrawal → Stripe Connect，并输入你的 Stripe 平台凭据
5. 卖家通过 Dokan 内置的 Stripe Connect 入驻流程连接其银行账户
6. 在 Dokan → Vendors 中手动批准或拒绝卖家申请

自定义 / 无头架构 — 使用 Stripe Connect 处理 KYC

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Create a Stripe Express account for a new seller and return the onboarding URL
async function onboardSeller(sellerId: string, sellerEmail: string): Promise<string> {
  // Create the Stripe Express account
  const account = await stripe.accounts.create({
    type: 'express',
    email: sellerEmail,
    capabilities: {
      transfers: { requested: true },
    },
  });

  // Store the Stripe account ID on the seller record
  await db.sellers.update(sellerId, { stripe_account_id: account.id });

  // Generate the onboarding link (valid for 24 hours)
  const accountLink = await stripe.accountLinks.create({
    account: account.id,
    refresh_url: `${process.env.APP_URL}/seller/onboarding/refresh`,
    return_url: `${process.env.APP_URL}/seller/onboarding/complete`,
    type: 'account_onboarding',
  });

  return accountLink.url; // send this URL to the seller
}

// Webhook handler: activate seller when Stripe confirms KYC is complete
async function handleStripeAccountUpdated(account: Stripe.Account): Promise<void> {
  const seller = await db.sellers.findByStripeAccountId(account.id);
  if (!seller) return;

  if (account.charges_enabled && account.payouts_enabled && seller.status !== 'active') {
    await db.sellers.update(seller.id, { status: 'active' });
    // Send welcome email to seller
  }
}

步骤 3：设置每位卖家的商品

Shopify（Webkul）

1. 已获批准的卖家登录其卖家控制面板：yourstore.com/seller/dashboard
2. 卖家在控制面板中添加产品——产品会先提交给你审批，通过后才能上架（可在 Webkul 设置中配置）
3. 你可以控制卖家是否能自行定价，或是否所有价格都必须经过你的审批
4. 产品图片、描述和库存均由卖家在其控制面板中管理

WooCommerce（Dokan）

1. 卖家访问其商店控制面板：yourstore.com/dashboard
2. 卖家通过 Dokan → Products → Add New 添加产品
3. 在 Dokan 设置中启用「Product Review」，要求新产品上架前必须经过你的审批
4. 卖家自行管理库存数量、产品变体和价格
5. 在 Dokan Pro 中，你可以按产品、类别或全局设置佣金率

步骤 4：配置佣金规则和付款

Shopify（Webkul）

1. 前往 Webkul → Commission 设置佣金率：
   • 全局佣金：例如，所有销售均收取 15%
   • 针对特定卖家的佣金：为特定卖家设置不同费率（例如，VIP 卖家为 10%）
   • 针对特定类别的佣金：按产品类别设置不同费率
2. 付款时会自动从每笔订单中扣除佣金
3. 在 Webkul → Payments → Seller Transactions 中跟踪卖家收入
4. 向卖家付款：前往 Webkul → Payments → Process Payout。选择卖家，然后点击 Process via Stripe Connect——资金将从你的 Stripe 余额转入卖家关联的账户

WooCommerce（Dokan）

1. 前往 Dokan → Settings → Selling → Commission 设置全局佣金率
2. 在 Dokan → Vendors → [Seller] → Commission 中为特定卖家设置不同费率
3. 卖家通过其控制面板申请提现（Dokan → Withdraw Requests）
4. 在 Dokan → Withdraw Requests → Pending 中审批提现申请
5. 通过 Stripe 自动付款：Dokan Pro 的 Stripe Connect 模块会自动处理已批准的提现申请

自定义 / 无头架构 — 佣金和付款逻辑

// Calculate commission and record seller earnings when an order is paid
async function recordSellerEarning(params: {
  orderId: string;
  sellerId: string;
  grossAmountCents: number;  // what buyer paid for this seller's items
  commissionRate: number;    // e.g., 0.15 for 15%
}): Promise<void> {
  const commissionCents = Math.round(params.grossAmountCents * params.commissionRate);
  const netAmountCents = params.grossAmountCents - commissionCents;

  // Funds held until return window closes (e.g., 30 days)
  const availableAt = new Date();
  availableAt.setDate(availableAt.getDate() + 30);

  await db.sellerEarnings.insert({
    seller_id: params.sellerId,
    order_id: params.orderId,
    gross_amount_cents: params.grossAmountCents,
    commission_cents: commissionCents,
    net_amount_cents: netAmountCents,
    status: 'held',             // becomes 'available' after return window
    available_at: availableAt,
  });
}

// Transfer available earnings to seller's Stripe account
async function payoutSeller(sellerId: string): Promise<void> {
  const seller = await db.sellers.findById(sellerId);
  const availableEarnings = await db.sellerEarnings.findAll({
    seller_id: sellerId,
    status: 'available',
    available_at: { lte: new Date() },
  });

  const totalCents = availableEarnings.reduce((s, e) => s + e.net_amount_cents, 0);
  if (totalCents < 100) return; // minimum payout $1.00

  // Transfer from your Stripe balance to seller's connected account
  const transfer = await stripe.transfers.create({
    amount: totalCents,
    currency: 'usd',
    destination: seller.stripe_account_id,
    metadata: { seller_id: sellerId },
  });

  // Mark earnings as paid out
  await db.sellerEarnings.updateMany(
    availableEarnings.map(e => e.id),
    { status: 'paid_out' }
  );
}

步骤 5：设置卖家控制面板

Shopify（Webkul）

• 卖家通过 Webkul 提供的控制面板 yourstore.com/seller/dashboard 查看订单、产品、收入摘要和付款记录
• 在 Webkul → Settings → Dashboard 中自定义控制面板的外观（颜色、徽标）

WooCommerce（Dokan）

• Dokan 提供完整的前端控制面板 yourstore.com/dashboard，包含销售分析、产品管理、提现申请和订单管理
• 可通过 Dokan 的模板覆盖功能高度自定义控制面板

最佳实践

• 所有卖家的付款都使用 Stripe Connect Express——Express 负责处理 KYC、银行账户验证和 IRS 1099-K 报告；自行构建这些功能成本高昂，且存在法律风险
• 在退货期限结束前暂缓支付资金——在买家的退货期限结束前，不要向卖家支付收入；提前支付意味着平台要承担退款损失
• 在确认订单的同一笔事务中记录佣金——绝不要通过可能失败的队列异步计算佣金；收入记录必须与订单原子化
• 通过电子邮件向卖家发送付款摘要——包含订单级明细的每周收入摘要有助于建立卖家信任并减少支持咨询
• 在 Stripe 入驻流程完成前禁止卖家发布商品——允许卖家发布商品前，先检查 Stripe 账户的 charges_enabled && payouts_enabled

常见问题

问题	解决方案
付款失败，但收益被标记为已支付	在 Stripe Connect 中，使用 transfer.created webhook 确认成功后，再将收益标记为 paid_out；切勿在发起转账的同一调用中将其标记为已支付
买家付款到账前，平台就向卖家付款	仅通过 payment_intent.succeeded webhook 触发付款资格，不要在创建结账会话时触发
卖家在 KYC 验证通过前就发布商品	允许发布商品前，检查 Stripe 账户状态（charges_enabled && payouts_enabled）；Webkul 和 Dokan 会自动执行此操作
卖家对佣金扣除提出异议	在每条 seller_earning 记录中保存佣金比率和总金额；在卖家控制面板中向卖家展示佣金计算历史

相关技能

• @multi-channel-selling
• @vendor-management
• @b2b-commerce
• @order-management-system