paypal-integration

PayPal 集成

概述

PayPal Checkout 允许购物者使用 PayPal 余额、Venmo、Pay Later（分期付款），或通过 PayPal 处理的银行卡付款。在德国、荷兰和巴西等 PayPal 占主导地位的市场，以及任何客户不愿输入银行卡信息的市场，它都特别有价值。所有主流平台都提供官方 PayPal 集成，只需凭据即可使用，无需为标准结账流程编写自定义代码。

何时使用此技能

• 在银行卡处理服务之外添加 PayPal 付款选项时
• 在商品页面或购物车中实现 PayPal Express Checkout 时（可减少购买步骤）
• 面向 PayPal 占主导地位的市场（德国、荷兰、巴西）时
• 添加 Venmo 或 Pay Later（分期付款）以吸引年轻购物者时

核心说明

第 1 步：创建并配置 PayPal Business 账户

1. 如果尚未拥有 PayPal Business 账户，请访问 paypal.com/business 注册
2. 验证您的企业身份（接收付款前必须完成）
3. 开发和测试时：访问 developer.paypal.com 注册并创建 sandbox 买家/卖家账户
4. 在 developer.paypal.com → My Apps → Create App 创建应用，以获取 Client ID 和 Secret

第 2 步：在您的平台上安装 PayPal

---

Shopify

PayPal Express Checkout 已内置于 Shopify 中，大多数商店默认启用。

验证或重新配置：

1. 前往 Settings → Payments
2. 在 Payment providers 下，点击 PayPal 或 Activate PayPal
3. 如果尚未连接，点击 Activate，然后使用 PayPal Business 账户登录并完成关联
4. 选择以下选项之一：
   • PayPal Express Checkout：经典结账流程（推荐）
   • PayPal Complete Payments：较新的集成，也支持 Venmo 和 Pay Later

启用 Venmo 和 Pay Later：

1. 在 PayPal Business 控制面板中，前往 Account Settings → Payment Preferences
2. 启用 Venmo 和 Pay Later——在 PayPal 账户中激活后，这些选项会自动显示在 Shopify 结账页面
3. 若要在商品页面显示 Pay Later 横幅：从 Shopify App Store 安装 PayPal Pay Later Messaging 应用

WooCommerce

1. 安装 WooCommerce PayPal Payments 插件（由 WooCommerce/PayPal 维护的官方插件，可从 WordPress.org 免费获取）
2. 前往 WooCommerce → Settings → Payments → PayPal Payments → Set Up
3. 点击 Connect to PayPal，并使用 PayPal Business 账户登录（通过 OAuth 设置，无需复制/粘贴 API 密钥）
4. 插件会自动启用：PayPal Standard、Venmo、Pay Later、银行卡字段和 PayPal Credit 选项
5. 在 WooCommerce → Settings → Payments → PayPal Payments → Smart Payment Buttons 下配置按钮位置：
   • 选择在哪些页面启用按钮：商品页面、购物车页面、结账页面
   • 配置按钮颜色（金色、蓝色、银色、白色、黑色）
6. 若要在商品页面显示 Pay Later 消息：前往插件设置中的 Pay Later Messaging 部分并启用

PayPal Checkout（替代方案，较旧的集成）： 较旧的 WooCommerce PayPal Checkout 插件仍可使用，但所有新设置都推荐使用较新的 WooCommerce PayPal Payments 插件。

BigCommerce

1. 前往 Settings → Payment Methods → Online Payment Methods
2. 找到 PayPal Powered by Braintree 并点击 Set Up
3. 点击 Connect with PayPal，并使用 PayPal Business 账户授权
4. 启用所需的付款方式：PayPal、Venmo、Pay Later
5. 在配置面板中设置要显示 PayPal 按钮的页面

此外，BigCommerce 还支持 PayPal Commerce Platform——前往 Settings → Payment Methods 并选择 PayPal Commerce Platform，即可使用完整的 PayPal 付款选项套件。

---

自定义／无头

对于无头店面，请使用 PayPal JavaScript SDK 和 Orders API v2：

加载 PayPal JavaScript SDK：

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD&intent=capture&components=buttons"></script>

在服务端创建 PayPal 订单：

// POST /api/paypal/create-order
async function createPayPalOrder(req, res) {
  const { cartId } = req.body;
  const cart = await db.carts.findUnique({ where: { id: cartId } });
  const accessToken = await getPayPalAccessToken();

  const orderRes = await fetch('https://api-m.paypal.com/v2/checkout/orders', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'PayPal-Request-Id': cartId, // Idempotency key
    },
    body: JSON.stringify({
      intent: 'CAPTURE',
      purchase_units: [{
        reference_id: cartId,
        amount: {
          currency_code: 'USD',
          value: cart.total.toFixed(2),
        },
      }],
    }),
  });

  const order = await orderRes.json();
  res.json({ id: order.id });
}

渲染 PayPal 按钮并捕获付款：

useEffect(() => {
  if (!window.paypal) return;

  window.paypal.Buttons({
    style: { layout: 'vertical', color: 'gold', shape: 'rect' },

    createOrder: async () => {
      const res = await fetch('/api/paypal/create-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ cartId }),
      });
      const data = await res.json();
      return data.id; // PayPal Order ID
    },

    onApprove: async (data) => {
      // Always capture server-side — never trust client-side only
      const res = await fetch('/api/paypal/capture-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ orderId: data.orderID, cartId }),
      });
      const result = await res.json();
      if (result.success) router.push(`/orders/${result.shopOrderId}/confirmation`);
    },

    onCancel: () => {
      // User closed PayPal popup — leave cart intact, show no error
    },

    onError: (err) => {
      console.error('PayPal error:', err);
      setError('PayPal encountered an error. Please try again or use a card.');
    },
  }).render('#paypal-button-container');
}, [cartId]);

在服务端捕获付款：

// POST /api/paypal/capture-order
async function capturePayPalOrder(req, res) {
  const { orderId, cartId } = req.body;
  const accessToken = await getPayPalAccessToken();

  const captureRes = await fetch(`https://api-m.paypal.com/v2/checkout/orders/${orderId}/capture`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'PayPal-Request-Id': `capture-${orderId}`, // Idempotency key
    },
  });

  const capture = await captureRes.json();
  if (capture.status !== 'COMPLETED') {
    return res.status(400).json({ error: 'Payment capture failed' });
  }

  // Create your internal order record
  const order = await createOrderFromCart(cartId, {
    paymentMethod: 'paypal',
    paypalOrderId: orderId,
    paypalCaptureId: capture.purchase_units[0].payments.captures[0].id,
  });

  res.json({ success: true, shopOrderId: order.id });
}

处理 PayPal webhook：

在 PayPal 开发者控制面板中注册以下 webhook：PAYMENT.CAPTURE.COMPLETED、PAYMENT.CAPTURE.REFUNDED、PAYMENT.CAPTURE.REVERSED。处理 webhook 前，请使用 PayPal 的签名验证 API 验证 webhook 签名。

第 3 步：使用 PayPal 沙盒进行测试

1. 前往 developer.paypal.com → Sandbox → Accounts，使用预先创建的沙盒买家和卖家账户
2. 设置环境变量以使用沙盒：

   PAYPAL_CLIENT_ID=<sandbox-client-id>
   PAYPAL_CLIENT_SECRET=<sandbox-client-secret>
   PAYPAL_API_BASE=https://api-m.sandbox.paypal.com
   

3. 使用沙盒买家账户凭据测试完整的购买流程
4. 确认 webhook 已触发，且处理程序能正确处理

最佳实践

• 始终在服务端捕获付款——不要只信任客户端的 onApprove 回调；始终从服务器使用 Orders API 捕获付款
• 使用 PayPal-Request-Id 标头——此幂等键可在请求重试时防止重复扣款
• 在商品页面启用 Pay Later 提示——在结账前显示“分 4 期免息支付，每期 $X”可提高 AOV；WooCommerce 插件已内置此功能
• 妥善处理 onCancel——用户关闭 PayPal 弹出窗口时，不要显示错误；让他们重试或选择其他付款方式即可
• 验证 webhook 签名——PayPal 可能会向你的 webhook 端点发送伪造的负载；务必验证 paypal-transmission-sig 标头

常见问题

问题	解决方案
出现“此卖家不接受付款”错误	确保你的 PayPal 账户已完成卖家入驻（验证电子邮件、关联银行账户）；同时确认沙盒和生产环境的凭据相匹配
某些浏览器会拦截 PayPal 弹出窗口	createOrder 回调必须在用户点击事件中立即返回值；任何异步延迟都可能触发弹出窗口拦截器——请在按钮渲染前完成服务器调用，或使用 PayPal 内置 API
webhook 在捕获完成前确认订单	使用 PAYMENT.CAPTURE.COMPLETED webhook（而非 CHECKOUT.ORDER.APPROVED）；后者会在资金捕获前触发
webhook 重试导致重复订单	创建新订单前，检查是否已存在具有该 PayPal 捕获 ID 的订单
WooCommerce PayPal 插件未显示 Venmo／Pay Later	必须在 PayPal Business 账户设置中启用 Venmo 和 Pay Later（仅在插件中启用还不够）——请在 PayPal 中检查 Account Settings → Payment Preferences
Shopify 重新连接后 PayPal 无法处理付款	在 Shopify → Settings → Payments 中断开并重新连接 PayPal 账户；旧的 OAuth 令牌有时会过期

相关技能

• @stripe-integration
• @checkout-flow-optimization
• @order-processing-pipeline
• @buy-now-pay-later