stripe-integration

Stripe 集成

概述

Stripe 是电商平台中支持最广泛的支付处理商。在 Shopify 上，它为 Shopify Payments 提供原生支持。在 WooCommerce 和 BigCommerce 上，官方插件只需最少配置即可提供完整的 Stripe Checkout。只有无头店面才需要自定义代码——即便如此，Stripe 托管的 Checkout 页面和 Elements 组件也能免去大部分复杂工作。

何时使用此技能

• 为现有商店添加 Stripe 作为支付处理商时
• 为新的 WooCommerce 或 BigCommerce 商店设置 Stripe 时
• 为欧洲客户实现符合 SCA 标准的结账时
• 设置 Webhook 处理程序以自动完成订单履约时
• 构建需要 Stripe 支付处理的自定义或无头店面时

核心说明

第 1 步：创建并配置 Stripe 账户

1. 在 stripe.com 注册——企业验证需要 1–3 个工作日
2. 完成 Stripe Dashboard → Activate account，开始接收实时付款
3. 在 Settings → Public details 下配置 Statement descriptor（显示在客户银行账单上的名称）
4. 如果希望 Stripe 自动处理税费计算，请在 Dashboard → Tax 下设置 Stripe Tax

第 2 步：在平台上安装 Stripe

---

Shopify

Shopify Payments 由 Stripe 提供支持。这是最简单的 Stripe 集成方式：

1. 前往 Settings → Payments → Shopify Payments → Complete account setup
2. 验证企业详情和银行信息
3. Shopify Payments 会自动处理：银行卡支付、Apple Pay、Google Pay、Shop Pay，以及（经过配置后）Klarna 和 Afterpay
4. 无需额外插件或 API 密钥——Shopify Payments 会处理所有事项

如果需要直接使用 Stripe（例如，使用 Shopify Payments 不支持的功能）：

1. 在 Settings → Payments → Add payment methods → Stripe 下安装 Stripe 支付服务商
2. 注意：Shopify 上的第三方支付服务商会收取额外交易费（0.5%–2%）；Shopify Payments 则不会

为 Shopify 配置 Stripe Webhook： Shopify Payments 的 Webhook 处理由 Shopify 内部完成。如果直接使用 Stripe，请在 Stripe Dashboard → Developers → Webhooks 下注册 Webhook 端点。

WooCommerce

1. 安装 WooCommerce Stripe Payment Gateway 插件（免费，可从 WordPress.org 获取，由 WooCommerce 提供）
2. 前往 WooCommerce → Settings → Payments → Stripe，然后点击 Enable
3. 输入从 Stripe Dashboard → Developers → API Keys 获取的 Publishable key 和 Secret key
4. 启用 Payment Request Buttons（Apple Pay、Google Pay）——这些按钮会自动显示在商品页和结账页上

启用其他支付方式：

• 前往 WooCommerce → Settings → Payments → Stripe 并启用：
  • Express Checkout（Apple Pay、Google Pay、Link）
  • SEPA Direct Debit（面向欧洲客户）
  • iDEAL（荷兰）、Bancontact（比利时）、Sofort（德国／奥地利）
  • Klarna 和 Afterpay（如符合条件）

设置 Webhook：

1. 在 Stripe 插件设置中，点击 Configure webhooks
2. 插件会自动向 Stripe 注册所需的 Webhook 端点
3. 在 Stripe Dashboard → Developers → Webhooks 中确认 Webhook 已启用

启用 Stripe Radar（欺诈防范）： Stripe Radar 默认已启用。在 Stripe Dashboard → Radar → Rules 下配置规则，以拦截或审核高风险交易。

BigCommerce

1. 前往 设置 → 支付方式 → 在线支付方式
2. 找到 Stripe，然后点击 设置
3. 输入 Stripe Dashboard 中的 Stripe API 密钥（可发布密钥和私密密钥）
4. 在 Stripe 配置面板中启用你想提供的支付方式
5. BigCommerce 会自动注册所需的 Stripe Webhook

启用 Stripe Link（已保存的卡片）： 在 BigCommerce 的 Stripe 设置中，启用 Stripe Link，让回头客可以使用已保存的支付信息一键付款。

---

自定义 / 无头架构

安装 Stripe SDK：

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

选项 A：Stripe Checkout（托管页面 — 最简单）

如需最快完成集成且无需构建支付表单：

// Server: create a Checkout Session
const session = await stripe.checkout.sessions.create({
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: { name: 'Order #' + orderNumber },
      unit_amount: Math.round(orderTotal * 100), // cents
    },
    quantity: 1,
  }],
  mode: 'payment',
  success_url: `${YOUR_DOMAIN}/orders/{CHECKOUT_SESSION_ID}/confirmation`,
  cancel_url: `${YOUR_DOMAIN}/cart`,
  metadata: { order_id: orderId },
});

// Redirect customer to session.url
res.redirect(session.url);

选项 B：使用 Stripe Elements 的 Payment Intents（自定义结账表单）

// Server: create a Payment Intent
const paymentIntent = await stripe.paymentIntents.create({
  amount: Math.round(orderTotal * 100), // cents
  currency: 'usd',
  automatic_payment_methods: { enabled: true }, // Enables all eligible methods
  metadata: { order_id: orderId, customer_email: customerEmail },
});
res.json({ clientSecret: paymentIntent.client_secret });

// Client: render the payment form using Stripe Elements
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

function CheckoutForm({ onSuccess }) {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e) {
    e.preventDefault();
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url: `${window.location.origin}/orders/confirmation` },
    });
    if (error) showError(error.message);
    // On success, Stripe redirects to return_url automatically
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe}>Pay Now</button>
    </form>
  );
}

export function PaymentPage({ clientSecret }) {
  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      <CheckoutForm />
    </Elements>
  );
}

处理用于履行订单的 Webhook：

// POST /api/webhooks/stripe
// IMPORTANT: use raw body parser — do not parse as JSON
export async function handleStripeWebhook(req, res) {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.rawBody,   // raw buffer — not JSON.parse'd
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'payment_intent.succeeded':
      await fulfillOrder(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      await handlePaymentFailed(event.data.object);
      break;
    case 'charge.refunded':
      await handleRefund(event.data.object);
      break;
    case 'charge.dispute.created':
      await handleDispute(event.data.object);
      break;
  }

  res.json({ received: true });
}

// Always check if already fulfilled — webhooks can arrive multiple times
async function fulfillOrder(paymentIntent) {
  const orderId = paymentIntent.metadata.order_id;
  const order = await db.orders.findUnique({ where: { id: orderId } });
  if (order.status !== 'pending') return; // Idempotency check

  await db.orders.update({ where: { id: orderId }, data: { status: 'confirmed', paidAt: new Date() } });
  await sendOrderConfirmationEmail(orderId);
}

本地 Webhook 测试：

# Install Stripe CLI and forward events to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe
# Copy the webhook signing secret printed by the CLI into your .env

第 3 步：PCI 合规性和 SCA

PCI DSS 适用范围： 使用 Stripe Elements 或 Stripe Checkout 可大幅减轻 PCI DSS 合规负担：

• SAQ A（22 项要求）：适用于使用 Stripe Checkout（托管页面）的情况——卡片数据不会经过你的服务器或页面
• SAQ A-EP（191 项要求）：适用于结账页面由你自己的域名提供，且 Stripe.js 在浏览器中对卡片进行令牌化的情况

WooCommerce Stripe 插件和 BigCommerce 的 Stripe 集成都使用 Stripe.js 进行令牌化，因此大多数商家符合 SAQ A-EP 的要求。

欧洲客户的 SCA（强客户身份验证）： 在 Payment Intents 中使用 automatic_payment_methods: { enabled: true }，即可在客户的银行要求时自动处理 3D Secure 验证。无需额外配置。

最佳实践

• 始终使用 Payment Intents — 旧版 Charges API 不支持 SCA，不建议用于新的集成
• 切勿记录或存储原始卡号 — 使用 Stripe Elements 或 Checkout，避免纳入 PCI 合规范围
• 使用 Webhook 事件履行订单 — 不要只依赖客户端重定向；客户可能会关闭浏览器窗口
• 确保所有 Webhook 处理程序都具备幂等性 — Stripe 可能会多次发送同一事件；处理前务必检查当前订单状态
• 为每个 Payment Intent 的 metadata 添加 order_id — 这有助于对账和争议管理
• 如果向多个司法管辖区销售，请使用 Stripe Tax — 在 Stripe Dashboard → Tax 中进行配置，而不是自行构建税费计算功能

常见问题

问题	解决方案
Webhook 签名验证失败	将原始请求正文（而非解析后的 JSON）传递给 constructEvent；配置框架，使其跳过对 Webhook 路由的 JSON 解析
未触发 3DS 验证	使用 automatic_payment_methods: { enabled: true }，而不要手动列出支付方式类型
WooCommerce Stripe 插件显示空白支付表单	检查 JavaScript 控制台错误；通常是 CSP（内容安全策略）阻止了 Stripe.js；将 js.stripe.com 添加到 CSP 允许列表中
Stripe 支付显示成功，但订单未确认	Webhook 是权威信号——如果 Webhook 处理程序出错，订单就不会确认；请在 Stripe Dashboard → Developers → Webhooks → [Event] 中查看 Webhook 日志
测试模式的扣款出现在正式数据中	确认你在生产环境中使用正式 API 密钥；Stripe Dashboard 有独立的正式 / 测试模式切换开关——请确认当前模式正确
货币金额错误	Stripe 使用货币的最小单位——$20.00 = 2000 美分；JPY ¥3,000 = 3000（无需乘算）

相关技能

• @checkout-flow-optimization
• @subscription-billing
• @paypal-integration
• @order-processing-pipeline
• @buy-now-pay-later