Stripe 接入教程：从注册到完成第一笔收款的全流程

Stripe 接入教程：从注册到完成第一笔收款的全流程

Stripe 是全球最受欢迎的在线支付平台之一，以优秀的开发者体验和丰富的 API 著称。无论是 SaaS 订阅、电商网站还是数字产品销售，Stripe 都能提供一站式支付解决方案。这篇教程按"注册账号 → 配置密钥 → 创建 PaymentIntent → 前端收集卡号 → Webhook 通知"的顺序，带你从零跑通第一笔真实收款，全程大约 30 分钟，且不需要依赖 Stripe 之外的其他支付服务。

一、注册 Stripe 账户

1.1 创建账户

1. 访问 Stripe 官网 点击"Start now"
2. 输入邮箱、姓名和密码
3. 验证邮箱地址
4. 激活账户后即可进入 Dashboard

1.2 账户模式

Stripe 提供两种模式：

开发阶段始终使用 Test 模式，上线前切换到 Live 模式。

1.3 获取 API 密钥

在 Dashboard → Developers → API Keys 中获取：

• Publishable Key（可发布密钥）：前端使用，以 pk_ 开头
• Secret Key（秘密密钥）：后端使用，以 sk_ 开头，必须保密

# 示例密钥（测试模式）
pk_test_51ABC...def
sk_test_51ABC...xyz

二、Stripe 支付流程架构

Stripe 推荐使用 Payment Intents API，支付流程如下：

1. 用户点击"支付"按钮
2. 前端请求后端创建 PaymentIntent
3. 后端调用 Stripe API 创建 PaymentIntent → 返回 client_secret
4. 前端使用 Stripe Elements 收集卡号信息
5. Stripe.js 将卡号加密后提交到 Stripe
6. Stripe 处理支付，返回结果
7. 前端显示结果
8. Webhook 通知后端支付结果

为什么推荐 Payment Intents 而不是旧的 Charges API？因为欧洲的 SCA（Strong Customer Authentication）法规要求大部分交易走 3D Secure 验证，Payment Intents 天然支持这种"异步确认"流程：先创建支付意图，用户完成验证，再最终确认。它把"授权"和"确认"拆开，也方便处理退款、部分退款和后续的订阅扣款。对照上面的流程：第 4、5 步的卡号收集与提交全部发生在浏览器端，你的服务器永远不接触明文卡号，PCI 合规范围被压到最小。

三、集成 Stripe 支付

3.1 后端创建 PaymentIntent（Node.js 示例）

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/create-payment-intent', async (req, res) => {
  try {
    const paymentIntent = await stripe.paymentIntents.create({
      amount: 1999, // 金额单位：分（$19.99）
      currency: 'usd',
      automatic_payment_methods: {
        enabled: true,
      },
      metadata: {
        order_id: req.body.orderId,
      },
    });

    res.json({
      clientSecret: paymentIntent.client_secret,
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

3.2 前端集成 Stripe Elements

<!-- HTML -->
<div id="payment-form">
  <div id="card-element"></div>
  <button id="submit-button">支付 $19.99</button>
  <div id="payment-message"></div>
</div>

<script src="https://js.stripe.com/v3/"></script>
<script>
const stripe = Stripe('pk_test_...');
const elements = stripe.elements();
const cardElement = elements.create('card');
cardElement.mount('#card-element');

const form = document.getElementById('payment-form');
form.addEventListener('submit', async (event) => {
  event.preventDefault();
  
  // 从后端获取 clientSecret
  const response = await fetch('/create-payment-intent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ orderId: '12345' }),
  });
  const { clientSecret } = await response.json();
  
  // 确认支付
  const { error, paymentIntent } = await stripe.confirmCardPayment(
    clientSecret,
    { payment_method: { card: cardElement } }
  );
  
  if (error) {
    showMessage(error.message);
  } else if (paymentIntent.status === 'succeeded') {
    showMessage('支付成功！');
  }
});
</script>

四、Webhook 配置

Webhook 是 Stripe 通知后端支付结果的关键机制。

4.1 设置 Webhook Endpoint

在 Stripe Dashboard → Developers → Webhooks 中添加 Endpoint：

• Endpoint URL：https://yourdomain.com/stripe/webhook
• 监听事件：payment_intent.succeeded、payment_intent.payment_failed

4.2 Webhook 处理代码

const endpointSecret = 'whsec_...';

app.post('/stripe/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      // 更新订单状态
      updateOrderStatus(paymentIntent.metadata.order_id, 'paid');
      break;
      
    case 'payment_intent.payment_failed':
      const failedPayment = event.data.object;
      updateOrderStatus(failedPayment.metadata.order_id, 'failed');
      break;
  }

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

4.3 Webhook 最佳实践

• 务必验证签名：用 stripe.webhooks.constructEvent 校验 stripe-signature，不要直接信任 POST 内容，否则任何人伪造请求都能触发"发货"逻辑。
• 接口要幂等：Stripe 会在失败时重试 webhook，同一事件可能收到多次，处理前先查订单状态，已处理过就直接返回 200。
• 响应要快：收到事件先返回 200，再异步处理业务逻辑，避免超时导致 Stripe 反复重试。
• 本地调试：用 Stripe CLI 的 stripe listen --forward-to localhost:3000/stripe/webhook 把线上事件转发到本地，开发期非常方便。

五、Stripe 支持的支付方式

六、费用与结算

6.1 Stripe 费率

标准费率：2.9% + $0.30/笔（美国卡）

6.2 结算周期

• 标准结算周期：7 天（美国用户 2 天）
• 可通过 Stripe Capital 加速结算

七、常见问题

为什么 Test 模式正常但 Live 模式失败？

原因可能是：①未完成账户验证；②业务信息不完整；③信用卡 3D 验证未通过

Stripe 与 PayPal 怎么选？

Stripe 更适合需要定制支付流程的开发者；PayPal 品牌信任度高，适合非技术用户快速上线。

如何避免欺诈？

• 启用 Stripe Radar（免费规则 + 付费高级规则）
• 设置 3D Secure 验证
• 检查 IP 地理位置与账单地址是否一致

测试卡与测试环境

Stripe 提供固定的测试卡号：4242 4242 4242 4242 是必然成功的卡，4000 0000 0000 0002 会触发拒付，4000 0027 6000 3184 需要 3DS 验证。把这三张卡固定进自动化测试，能覆盖"成功、拒绝、需验证"三条主要路径。测试模式下所有交易都不会真实扣款，可以放心反复调试。

八、集成方式怎么选：Checkout 与 Payment Element

Stripe 主推两种集成方式，各有适用场景：

一个新开的订阅型 SaaS 常用套路：先用 Checkout 最快跑通收款，等用户量起来、想优化转化率时，再迁移到 Payment Elements 自定义页面。两种方式都兼容订阅（Subscriptions）与发票（Invoices），迁移时业务代码基本不用改。

九、总结

Stripe 以其简洁的 API 和完善的文档成为开发者首选的支付平台。本文介绍的 Payment Intents API 是当前推荐的集成方式，支持 SCA（Strong Customer Authentication）合规要求。建议在正式上线前，充分测试各种支付场景，确保用户体验流畅。

参考：Stripe Payment Intents 文档 https://docs.stripe.com/payments/payment-intents；收款指南 https://docs.stripe.com/payments/accept-a-payment；Stripe CLI https://docs.stripe.com/stripe-cli