bowong
/
bw-mini-app-server
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bw-mini-app-server/STRIPE_INTEGRATION_GUIDE.md

7.0 KiB
Raw Blame History

Stripe国际支付集成指南

概述

本项目已成功集成Stripe国际信用卡支付功能，支持多种国际货币（USD、EUR、GBP、JPY等）的在线支付。Stripe适配器已完整实现并集成到现有的统一支付架构中。

功能特性

✅ 已实现功能

  1. 支付订单管理

    • 创建Stripe PaymentIntent
    • 查询支付状态
    • 支持多种国际货币

  2. Webhook处理

    • 安全的签名验证
    • 异步支付结果通知
    • 订单状态同步

  3. 退款管理

    • 申请退款
    • 查询退款状态
    • 部分退款支持

  4. 安全特性

    • Webhook签名验证
    • 环境变量配置管理
    • 错误处理和日志记录

  5. API接口

    • RESTful API设计
    • Swagger文档自动生成
    • 完整的DTO验证

环境配置

必需的环境变量

在.env文件中添加以下Stripe配置：

# Stripe配置
STRIPE_SECRET_KEY=sk_test_your_secret_key_here
STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here  
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# 服务器配置（用于回调URL）
SERVER_URL=https://your-domain.com

获取Stripe密钥

  1. 注册Stripe账号

  2. 获取API密钥

    • 登录Stripe Dashboard
    • 进入"开发者" -> "API密钥"
    • 复制可发布密钥和密钥

  3. 设置Webhook

    • 进入"开发者" -> "Webhook"
    • 添加端点：https://your-domain.com/api/v1/payment/stripe/webhook
    • 选择事件：payment_intent.succeeded
    • 复制签名密钥

API使用指南

1. 创建支付订单

POST /api/v1/payment/stripe/create-order
Content-Type: application/json

{
  "userId": "user_123",
  "businessType": "credit_purchase",
  "businessId": "credits_500",
  "amount": 4800,
  "currency": "USD",
  "description": "购买500积分包",
  "customerEmail": "user@example.com"
}

响应示例：

{
  "orderId": "order_123",
  "paymentIntentId": "pi_test_123",
  "clientSecret": "pi_test_123_secret_abc",
  "publishableKey": "pk_test_123",
  "amount": 4800,
  "currency": "USD",
  "status": "pending",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

2. 查询订单状态

GET /api/v1/payment/stripe/order/{orderId}

3. 申请退款

POST /api/v1/payment/stripe/refund
Content-Type: application/json

{
  "orderId": "order_123",
  "refundAmount": 2400,
  "reason": "用户申请退款"
}

4. 查询退款状态

GET /api/v1/payment/stripe/refund/{refundId}

5. 获取支持的货币

GET /api/v1/payment/stripe/supported-currencies

前端集成示例

React + Stripe Elements

import { loadStripe } from '@stripe/stripe-js';
import {
  Elements,
  CardElement,
  useStripe,
  useElements
} from '@stripe/react-stripe-js';

const stripePromise = loadStripe('pk_test_your_publishable_key');

function PaymentForm({ clientSecret }) {
  const stripe = useStripe();
  const elements = useElements();
  
  const handleSubmit = async (event) => {
    event.preventDefault();
    
    if (!stripe || !elements) return;
    
    const cardElement = elements.getElement(CardElement);
    
    const { error, paymentIntent } = await stripe.confirmCardPayment(
      clientSecret,
      {
        payment_method: {
          card: cardElement,
          billing_details: {
            email: 'user@example.com',
          },
        }
      }
    );
    
    if (error) {
      console.error('支付失败:', error);
    } else {
      console.log('支付成功:', paymentIntent);
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <CardElement />
      <button type="submit" disabled={!stripe}>
        支付
      </button>
    </form>
  );
}

function App() {
  const [clientSecret, setClientSecret] = useState('');
  
  // 创建支付订单获取clientSecret
  useEffect(() => {
    fetch('/api/v1/payment/stripe/create-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId: 'user_123',
        businessType: 'credit_purchase',
        businessId: 'credits_500',
        amount: 4800,
        currency: 'USD'
      })
    })
    .then(res => res.json())
    .then(data => setClientSecret(data.clientSecret));
  }, []);
  
  return (
    <Elements stripe={stripePromise}>
      <PaymentForm clientSecret={clientSecret} />
    </Elements>
  );
}

支持的货币

货币代码 货币名称 符号 最小单位
USD 美元 $ 2位小数
EUR 欧元 € 2位小数
GBP 英镑 £ 2位小数
JPY 日元 ¥ 0位小数
AUD 澳元 A$ 2位小数
CAD 加元 C$ 2位小数
SGD 新加坡元 S$ 2位小数
HKD 港币 HK$ 2位小数

测试

运行单元测试

# 运行Stripe适配器测试
npm test stripe-payment.adapter.spec.ts

# 运行所有支付相关测试
npm test payment

测试用卡号

Stripe提供以下测试卡号：

  • 成功支付: 4242 4242 4242 4242
  • 需要验证: 4000 0025 0000 3155
  • 被拒绝: 4000 0000 0000 0002
  • 余额不足: 4000 0000 0000 9995

使用任意未来日期作为过期时间，任意3位数字作为CVC。

监控和日志

日志级别

  • INFO: 正常的支付流程日志
  • WARN: 配置问题和可恢复错误
  • ERROR: 支付失败和系统错误

关键监控指标

  1. 支付成功率
  2. 响应时间
  3. 错误率
  4. 退款处理时间

安全注意事项

  1. 密钥管理

    • 绝不在客户端暴露密钥
    • 使用环境变量存储敏感信息
    • 定期轮换API密钥

  2. Webhook安全

    • 始终验证Webhook签名
    • 使用HTTPS端点
    • 实现幂等性处理

  3. 金额处理

    • 服务端验证所有金额
    • 使用整数避免浮点精度问题
    • 实现金额限制和验证

故障排查

常见问题

  1. 支付失败

    • 检查Stripe密钥配置
    • 验证货币代码格式
    • 确认金额范围有效

  2. Webhook失败

    • 验证端点URL可访问
    • 检查签名密钥配置
    • 确认事件类型选择

  3. 退款问题

    • 确认订单支付成功
    • 检查退款金额限制
    • 验证Charge ID存在

调试步骤

  1. 查看应用日志
  2. 检查Stripe Dashboard事件
  3. 验证Webhook配置
  4. 测试API端点连通性

部署注意事项

生产环境

  1. 使用生产环境Stripe密钥
  2. 配置HTTPS回调地址
  3. 设置适当的日志级别
  4. 配置监控和告警

性能优化

  1. 使用数据库连接池
  2. 实现适当的缓存策略
  3. 配置合理的超时时间
  4. 监控内存和CPU使用

更新日志

  • v1.0.0: 初始Stripe集成实现
    • 支付订单创建
    • Webhook处理
    • 退款功能
    • 多货币支持
    • 完整测试覆盖

技术支持

如有问题，请参考：

  1. Stripe官方文档
  2. 项目API文档
  3. 查看应用日志和错误信息