init: mipu-open 对外开放项目统一管理仓库
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
杨柳杰
302
docs/04-02_booking-payment.md
Normal file
302
docs/04-02_booking-payment.md
Normal file
@@ -0,0 +1,302 @@
|
||||
<!-- mipuyun-api-doc: booking-payment -->
|
||||
# booking/payment - 支付
|
||||
|
||||
# 更新支付信息(booking/payment) API 说明文档
|
||||
|
||||
## 使用场景
|
||||
|
||||
> 1. 客户完成 booking/hold 下单后，需要更新订单的支付信息（如支付方式、信用卡信息等）
|
||||
> 2. 用于在支付流程中记录或更新支付相关信息
|
||||
> 3. 使用 Apple Pay 支付时，可指定设备标签来选择执行任务的设备
|
||||
|
||||
## 错误场景(不应该使用本接口的场景)
|
||||
|
||||
> 1. 未完成 booking/hold 下单，订单不存在时
|
||||
> 2. orderId 为空或未提供时
|
||||
> 3. 订单不属于当前客户（clientCode 不匹配）时
|
||||
|
||||
## 性能指标
|
||||
|
||||
> - 响应速度：98% 的请求响应速度 < 2000ms
|
||||
> - 接口成功率：> 99%
|
||||
|
||||
## 请求说明
|
||||
|
||||
| **请求地址** | https://${endpoint}/booking/payment |
|
||||
| --- | --- |
|
||||
| **请求方法** | POST |
|
||||
|
||||
## 请求参数
|
||||
|
||||
### Header
|
||||
|
||||
| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Content-Type | String | 是 | application/json | 固定值，指定请求体格式为 JSON |
|
||||
| Accept-Encoding | String | 是 | gzip, deflate, br | 必须要填写，否则服务器会拒绝。 |
|
||||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||||
|
||||
###
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"orderId": "abbc4b57fb75",
|
||||
"proxy": "myproxy-us",
|
||||
"paymentMethod": "CREDIT_CARD",
|
||||
"retryCount": 0,
|
||||
"creditCard": {
|
||||
"number": "4111111111111111",
|
||||
"CVV": "123",
|
||||
"expiryMonth": "12",
|
||||
"expiryYear": "25",
|
||||
"lastName": "Doe",
|
||||
"firstName": "John",
|
||||
"country": "US"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 参数详情
|
||||
|
||||
| **参数名称** | **类型** | **是否必选** | **示例值（默认值）** | **说明** |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| orderId | String | **是** | abbc4b57fb75 | 客户的订单号，必须是通过 booking/hold 创建的订单 |
|
||||
| proxy | String | 是 | | 本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-US,US代表美国 |
|
||||
| paymentMethod | String | 否 | "CREDIT_CARD" | 支付方式代码：<br>**BALANCE**：余额支付<br>**CREDIT_CARD**：信用卡<br>**APPLE_PAY**：Apple Pay（支持设备标签） |
|
||||
| retryCount | Integer | 否 | 0 | 支付重试次数，默认为 0（不重试） |
|
||||
| creditCard | Object | 条件必填 | | 信用卡信息对象，当 paymentMethod 为 CREDIT_CARD 时必填 |
|
||||
| ├─ number | String | **条件必填** | "4111111111111111" | 信用卡号（13-19 位数字） |
|
||||
| ├─ CVV | String | **条件必填** | "123" | CVV 安全码（3-4 位数字） |
|
||||
| ├─ expiryMonth | String | **条件必填** | "12" | 有效期月份（1-2 位数字） |
|
||||
| ├─ expiryYear | String | **条件必填** | "25" | 有效期年份（2 或 4 位数字） |
|
||||
| ├─ lastName | String | **条件必填** | "Doe" | 持卡人姓 |
|
||||
| ├─ firstName | String | **条件必填** | "John" | 持卡人名 |
|
||||
| ├─ country | String | **条件必填** | "US" | 持卡人国家（二字码） |
|
||||
| ├─ province | String | 否 | | 持卡人省份/州 |
|
||||
| ├─ city | String | 否 | | 持卡人城市 |
|
||||
| ├─ postCode | String | 否 | | 持卡人邮编 |
|
||||
| ├─ address | String | 否 | | 持卡人地址 |
|
||||
| ├─ phone | String | 否 | | 持卡人电话（实体卡时使用） |
|
||||
| ├─ email | String | 否 | | 持卡人邮箱（实体卡时使用） |
|
||||
| ├─ maximumPaymentAmount | BigDecimal | 否 | | 最大支付金额 |
|
||||
| └─ reusable | Boolean | 否 | false | 是否为多次卡（默认单次卡） |
|
||||
| deviceTag | String | 否 | "EUR" | 设备标签，仅当 paymentMethod 为 APPLE_PAY 时可选，用于指定执行任务的设备 |
|
||||
|
||||
### 设备标签说明 (deviceTag)
|
||||
|
||||
- **适用场景**：仅当 `paymentMethod` 为 `APPLE_PAY` 时有效
|
||||
- **作用**：指定执行任务的设备标签，系统会优先分配有对应标签的设备
|
||||
- **可选性**：留空则自动分配设备
|
||||
- **示例**：
|
||||
```json
|
||||
{
|
||||
"orderId": "abbc4b57fb75",
|
||||
"paymentMethod": "APPLE_PAY",
|
||||
"deviceTag": "EUR"
|
||||
}
|
||||
```
|
||||
|
||||
## 返回参数
|
||||
|
||||
### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Payment info updated successfully",
|
||||
"orderId": "abbc4b57fb75"
|
||||
}
|
||||
```
|
||||
|
||||
### 失败响应
|
||||
|
||||
#### 缺少 orderId
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"msg": "orderId is required"
|
||||
}
|
||||
```
|
||||
|
||||
#### 订单不存在
|
||||
```json
|
||||
{
|
||||
"code": 404,
|
||||
"msg": "Booking not found",
|
||||
"orderId": "abbc4b57fb75"
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新失败
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"msg": "Failed to update payment info",
|
||||
"orderId": "abbc4b57fb75"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
| **参数名称** | **类型** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| code | Integer | 0 | 系统状态码<br>**0**：成功<br>**400**：缺少必填参数（orderId）<br>**404**：订单不存在或不属于当前客户<br>**500**：更新支付信息失败 |
|
||||
| msg | String | "Payment info updated successfully" | 系统消息：成功时返回成功提示，失败时返回具体错误信息 |
|
||||
| orderId | String | "abbc4b57fb75" | 客户的订单号，与请求中的 orderId 一致 |
|
||||
|
||||
## 业务流程
|
||||
|
||||
### 支付信息更新流程
|
||||
|
||||
```
|
||||
1. 客户完成航班搜索（shopping/search）
|
||||
↓
|
||||
2. 客户选择航班并验价（shopping/select）
|
||||
↓
|
||||
3. 客户提交订单（booking/hold）→ 获取 orderId
|
||||
↓
|
||||
4. 客户选择支付方式，调用支付接口（booking/payment）
|
||||
↓
|
||||
5. 支付完成
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 为什么 orderId 是必填的？
|
||||
|
||||
orderId 是订单的唯一标识符，系统需要通过它来：
|
||||
1. 定位到具体的订单
|
||||
2. 验证订单是否属于当前客户（通过 clientCode）
|
||||
3. 确保只有合法的订单才能更新支付信息
|
||||
|
||||
### paymentMethod 支持哪些支付方式？
|
||||
|
||||
系统支持三种支付方式：**BALANCE**（余额支付）、**CREDIT_CARD**（信用卡）、**APPLE_PAY**（Apple Pay，支持设备标签）。详见上方参数表格中的 paymentMethod 说明。
|
||||
|
||||
### Apple Pay 中的 deviceTag 是什么？
|
||||
|
||||
`deviceTag` 是设备标签，用于指定执行 Apple Pay 支付任务的设备：
|
||||
- 仅在 `paymentMethod` 为 `APPLE_PAY` 时有效
|
||||
- 可以指定有特定标签的设备执行任务
|
||||
- 留空则系统自动分配可用设备
|
||||
- 示例：`"deviceTag": "EUR"` 表示优先使用欧洲地区的设备
|
||||
|
||||
### 信用卡信息安全吗？
|
||||
|
||||
本接口仅用于记录支付信息到系统中。实际的支付处理通常由第三方支付网关完成，建议：
|
||||
1. 在前端不要存储真实的完整信用卡号
|
||||
2. 使用 PCI DSS 合规的支付网关处理实际支付
|
||||
3. 仅存储支付网关返回的支付令牌（token）
|
||||
|
||||
### 如果订单不存在会怎样？
|
||||
|
||||
接口会返回 `code: 404` 和 `msg: "Booking not found"`。这种情况通常由以下原因造成：
|
||||
1. orderId 错误或不存在
|
||||
2. 订单属于其他客户（clientCode 不匹配）
|
||||
3. 订单已过期或被删除
|
||||
|
||||
## 业务案例
|
||||
|
||||
### 更新信用卡支付信息
|
||||
|
||||
#### 请求（Request）
|
||||
|
||||
```json
|
||||
{
|
||||
"orderId": "abbc4b57fb75",
|
||||
"paymentMethod": "CREDIT_CARD",
|
||||
"creditCard": {
|
||||
"number": "4111111111111111",
|
||||
"CVV": "123",
|
||||
"expiryMonth": "12",
|
||||
"expiryYear": "25",
|
||||
"lastName": "Doe",
|
||||
"firstName": "John",
|
||||
"country": "US"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应（Response）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Payment info updated successfully",
|
||||
"orderId": "abbc4b57fb75"
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 Apple Pay 并指定设备标签
|
||||
|
||||
#### 请求（Request）
|
||||
|
||||
```json
|
||||
{
|
||||
"orderId": "abbc4b57fb75",
|
||||
"paymentMethod": "APPLE_PAY",
|
||||
"deviceTag": "EUR"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应（Response）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Payment info updated successfully",
|
||||
"orderId": "abbc4b57fb75"
|
||||
}
|
||||
```
|
||||
|
||||
### 缺少 orderId 的错误请求
|
||||
|
||||
#### 请求（Request）
|
||||
|
||||
```json
|
||||
{
|
||||
"paymentMethod": "CREDIT_CARD"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应（Response）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"msg": "orderId is required"
|
||||
}
|
||||
```
|
||||
|
||||
### 订单不存在的错误请求
|
||||
|
||||
#### 请求（Request）
|
||||
|
||||
```json
|
||||
{
|
||||
"orderId": "nonexistent-order-id",
|
||||
"paymentMethod": "CREDIT_CARD"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应（Response）
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 404,
|
||||
"msg": "Booking not found",
|
||||
"orderId": "nonexistent-order-id"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 | 处理建议 |
|
||||
| --- | --- | --- |
|
||||
| 0 | 成功 | 支付信息已成功更新 |
|
||||
| 400 | 请求参数错误 | 检查是否提供了必填的 orderId |
|
||||
| 404 | 订单不存在 | 确认订单 ID 是否正确，且订单属于当前客户 |
|
||||
| 500 | 服务器内部错误 | 系统处理异常，请稍后重试或联系技术支持 |
|
||||
Reference in New Issue
Block a user