💳 网站集成 Stripe 支付全流程配置指南

本文档详细讲解如何从零开始配置并集成 Stripe 支付系统，包含账户设置、API Key、环境变量、前后端代码、Webhook 以及调试流程。

📋 一、前提条件

组件	说明
Stripe 账号	前往 https://stripe.com 注册
Node.js 环境	Node.js ≥ 18
前端框架	可使用 React / Vue / Next.js / 原生 HTML
后端框架	Express / NestJS / Django / Laravel 等皆可
HTTPS 域名	必须在生产环境中使用（测试模式可用 localhost）

⚙️ 二、Stripe 账户配置

1. 启用测试模式

登录 Stripe Dashboard
点击右上角 “View test data”
进入测试模式后所有支付均为虚拟交易

2. 获取 API 密钥

路径：Developers → API keys

Key 名称	用途	使用场景
Publishable key (`pk_test_...`)	公钥	前端发起支付请求
Secret key (`sk_test_...`)	私钥	后端创建支付会话、处理订单

⚠️ 重要： Secret key 只能存在后端，绝不能暴露在前端代码中。

🧩 三、项目结构示例

my-app/
│
├── server/
│   ├── server.js          # 后端 Express 服务
│   ├── .env               # Stripe 环境变量配置
│
├── client/
│   ├── package.json
│   ├── src/
│   │   └── CheckoutButton.jsx
│
└── README.md

🔐 四、配置环境变量

在 server/.env 中添加以下内容：

STRIPE_SECRET_KEY=sk_test_你的SecretKey
STRIPE_WEBHOOK_SECRET=whsec_你的Webhook签名
CLIENT_URL=http://localhost:5173

在后端通过 dotenv 加载：

npm install dotenv

// server.js 顶部引入
import dotenv from "dotenv";
dotenv.config();

🏗️ 五、后端代码（Express 示例）

// server/server.js
import express from "express";
import Stripe from "stripe";
import dotenv from "dotenv";
import cors from "cors";

dotenv.config();

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

app.use(cors());
app.use(express.json());

// ✅ 创建 Checkout Session
app.post("/create-checkout-session", async (req, res) => {
  const { items } = req.body;

  const lineItems = items.map(item => ({
    price_data: {
      currency: "usd",
      product_data: { name: item.name },
      unit_amount: item.price * 100, // 单位: 美分
    },
    quantity: item.quantity,
  }));

  try {
    const session = await stripe.checkout.sessions.create({
      payment_method_types: ["card"],
      mode: "payment",
      line_items: lineItems,
      success_url: `${process.env.CLIENT_URL}/success`,
      cancel_url: `${process.env.CLIENT_URL}/cancel`,
    });

    res.json({ url: session.url });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// ✅ Stripe Webhook（监听支付结果）
import bodyParser from "body-parser";
app.post(
  "/webhook",
  bodyParser.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["stripe-signature"];
    let event;

    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (err) {
      console.error("⚠️ Webhook signature verification failed:", err.message);
      return res.sendStatus(400);
    }

    if (event.type === "checkout.session.completed") {
      const session = event.data.object;
      console.log("✅ 支付成功:", session);
      // TODO: 更新数据库订单状态
    }

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

app.listen(4242, () => console.log("🚀 Server running on http://localhost:4242"));

💻 六、前端代码（React 示例）

安装 Stripe SDK：

npm install @stripe/stripe-js

示例组件：

// client/src/CheckoutButton.jsx
import React from "react";
import { loadStripe } from "@stripe/stripe-js";

const stripePromise = loadStripe("pk_test_你的PublishableKey");

export default function CheckoutButton({ items }) {
  const handleCheckout = async () => {
    const stripe = await stripePromise;

    const response = await fetch("http://localhost:4242/create-checkout-session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ items }),
    });

    const session = await response.json();
    window.location.href = session.url;
  };

  return (
    <button
      onClick={handleCheckout}
      className="px-4 py-2 bg-indigo-600 text-white rounded"
    >
      立即支付
    </button>
  );
}

🔄 七、Webhook 配置（Stripe 控制台）

登录 Stripe Dashboard → Developers → Webhooks
点击 “Add endpoint”
输入你的后端 Webhook 地址，例如：
```
https://example.com/webhook
```
或本地调试：
```
http://localhost:4242/webhook
```
选择事件类型：
- checkout.session.completed
- payment_intent.succeeded
- payment_intent.payment_failed
保存后获取 Signing Secret（保存到 .env 的 STRIPE_WEBHOOK_SECRET）

🧪 八、本地调试（使用 Stripe CLI）

Stripe 提供 CLI 工具，可以让你本地测试 Webhook。

# 安装 Stripe CLI
brew install stripe/stripe-cli/stripe

# 登录
stripe login

# 启动本地转发
stripe listen --forward-to localhost:4242/webhook

输出中会显示类似：

Ready! Your webhook signing secret is whsec_12345...

💳 九、测试支付卡号

在测试模式下使用以下卡号：

卡号	说明
`4242 4242 4242 4242`	成功支付
`4000 0000 0000 9995`	支付失败
`4000 0027 6000 3184`	需要 3D Secure 验证

任意未来日期、任意 CVC 均可。

🧾 十、安全与上线注意事项

永远不要在前端使用 Secret Key
使用 .env 管理敏感配置
生产环境使用 HTTPS
支付金额必须在后端计算
通过 Webhook 验证支付状态，而不是前端 URL
切换到 Live 模式时更新：
- pk_live_...
- sk_live_...
- whsec_...

📚 十一、参考文档

✅ 至此，Stripe 支付系统已完成完整集成与配置！

从账户 → 环境变量 → 后端 → 前端 → Webhook → 测试，全流程打通。

本文由萧兮的博客原创发布，欢迎转载，转载务必保留原文链接。

萧兮的博客：https://www.20010515.xyz · 原文：https://www.20010515.xyz/posts/35045f26-7419-42b1-9d4a-fbb29f5924a2