mipu-open/docs/04-02_booking-payment.md

<!-- 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 | 服务器内部错误 | 系统处理异常，请稍后重试或联系技术支持 |