bw-mini-app-server/STRIPE_INTEGRATION_GUIDE.md

# Stripe国际支付集成指南

## 概述

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

## 功能特性

### ✅ 已实现功能

1. **支付订单管理**
   - 创建Stripe PaymentIntent
   - 查询支付状态
   - 支持多种国际货币

2. **Webhook处理**
   - 安全的签名验证
   - 异步支付结果通知
   - 订单状态同步

3. **退款管理**
   - 申请退款
   - 查询退款状态
   - 部分退款支持

4. **安全特性**
   - Webhook签名验证
   - 环境变量配置管理
   - 错误处理和日志记录

5. **API接口**
   - RESTful API设计
   - Swagger文档自动生成
   - 完整的DTO验证

## 环境配置

### 必需的环境变量

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

```bash
# 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账号**
   - 访问 [stripe.com](https://stripe.com)
   - 创建账号并完成验证

2. **获取API密钥**
   - 登录Stripe Dashboard
   - 进入"开发者" -> "API密钥"
   - 复制可发布密钥和密钥

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

## API使用指南

### 1. 创建支付订单

```bash
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"
}
```

**响应示例：**
```json
{
  "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. 查询订单状态

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

### 3. 申请退款

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

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

### 4. 查询退款状态

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

### 5. 获取支持的货币

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

## 前端集成示例

### React + Stripe Elements

```javascript
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位小数 |

## 测试

### 运行单元测试

```bash
# 运行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官方文档](https://stripe.com/docs)
2. [项目API文档](/docs)
3. 查看应用日志和错误信息