83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
|
# PayPal订单生命周期和字段填充说明
|
|||
|
|
|
|||
|
|
## 订单状态流转
|
|||
|
|
|
|||
|
|
PayPal订单会经历以下状态：
|
|||
|
|
|
|||
|
|
1. **CREATED** - 订单已创建（初始状态）
|
|||
|
|
2. **PAYER_ACTION_REQUIRED** - 需要付款人操作（跳转到PayPal登录页）
|
|||
|
|
3. **APPROVED** - 订单已批准（用户在PayPal批准支付）
|
|||
|
|
4. **COMPLETED** - 订单已完成（订单被捕获后）
|
|||
|
|
|
|||
|
|
## 字段填充时机
|
|||
|
|
|
|||
|
|
### 创建订单时（CREATED状态）
|
|||
|
|
|
|||
|
|
以下字段在创建订单时通常为 **null**，这是**正常现象**：
|
|||
|
|
|
|||
|
|
- `payer_email` - null（用户尚未登录PayPal）
|
|||
|
|
- `payer_name` - null（用户尚未登录PayPal）
|
|||
|
|
- `payer_id` - null（用户尚未登录PayPal）
|
|||
|
|
- `payment_status` - null（尚未支付）
|
|||
|
|
- `capture_id` - null（尚未捕获订单）
|
|||
|
|
|
|||
|
|
**原因**：创建订单时，用户还没有在PayPal登录和批准支付，所以PayPal不会返回这些信息。
|
|||
|
|
|
|||
|
|
### 用户批准订单后（APPROVED状态）
|
|||
|
|
|
|||
|
|
以下字段会被填充：
|
|||
|
|
|
|||
|
|
- `payer_email` - 用户PayPal邮箱
|
|||
|
|
- `payer_name` - 用户PayPal姓名
|
|||
|
|
- `payer_id` - 用户PayPal账户ID
|
|||
|
|
- `payment_status` - 仍为null（尚未捕获）
|
|||
|
|
- `capture_id` - 仍为null（尚未捕获）
|
|||
|
|
|
|||
|
|
**触发时机**：
|
|||
|
|
- 用户点击"立即支付"后跳转到PayPal
|
|||
|
|
- 用户在PayPal登录并批准支付
|
|||
|
|
- 系统通过Webhook事件 `CHECKOUT.ORDER.APPROVED` 或查询订单详情获取
|
|||
|
|
|
|||
|
|
### 订单被捕获后（COMPLETED状态）
|
|||
|
|
|
|||
|
|
以下字段会被填充：
|
|||
|
|
|
|||
|
|
- `payment_status` - 支付状态（如：COMPLETED）
|
|||
|
|
- `capture_id` - 支付捕获ID
|
|||
|
|
|
|||
|
|
**触发时机**：
|
|||
|
|
- 调用 `/api/paypal/orders/{orderId}/capture` 接口捕获订单
|
|||
|
|
- 系统通过Webhook事件 `PAYMENT.CAPTURE.COMPLETED` 获取
|
|||
|
|
|
|||
|
|
## 与沙箱测试的关系
|
|||
|
|
|
|||
|
|
**这些字段为null与沙箱测试环境无关**，这是PayPal订单的正常生命周期：
|
|||
|
|
|
|||
|
|
- 在**生产环境**中，如果订单状态为CREATED，这些字段同样为null
|
|||
|
|
- 只有在用户完成PayPal登录、批准支付、订单被捕获后，这些字段才会被填充
|
|||
|
|
- 沙箱环境和生产环境的行为是一致的
|
|||
|
|
|
|||
|
|
## 如何查看完整信息
|
|||
|
|
|
|||
|
|
1. **查看 `order_data` 字段**：该字段存储了PayPal返回的完整JSON响应，包含所有信息
|
|||
|
|
2. **查询订单详情**：调用 `/api/paypal/orders/{orderId}` 接口，系统会自动更新订单信息
|
|||
|
|
3. **等待Webhook事件**：PayPal会发送Webhook事件，系统会自动更新订单信息
|
|||
|
|
|
|||
|
|
## 代码更新逻辑
|
|||
|
|
|
|||
|
|
系统会在以下时机自动更新订单信息：
|
|||
|
|
|
|||
|
|
1. **创建订单时**：调用 `createPaymentOrder` 方法
|
|||
|
|
2. **查询订单时**：调用 `getOrder` 接口，自动调用 `updateOrderFromPayPal` 方法
|
|||
|
|
3. **捕获订单时**：调用 `captureOrder` 接口，自动调用 `updateOrderFromPayPal` 方法
|
|||
|
|
4. **Webhook事件**：处理Webhook事件时，自动调用 `updateOrderFromPayPal` 方法
|
|||
|
|
|
|||
|
|
## 建议
|
|||
|
|
|
|||
|
|
如果需要在订单创建后立即获取payer信息，可以：
|
|||
|
|
|
|||
|
|
1. 在用户从PayPal返回后，调用 `getOrder` 接口查询订单详情
|
|||
|
|
2. 配置Webhook监听 `CHECKOUT.ORDER.APPROVED` 事件
|
|||
|
|
3. 在订单确认页面加载时，主动查询一次PayPal订单详情
|
|||
|
|
|