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

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

请求体

{
  "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"	支付方式代码： BALANCE：余额支付 CREDIT_CARD：信用卡 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 时有效
• 作用：指定执行任务的设备标签，系统会优先分配有对应标签的设备
• 可选性：留空则自动分配设备
• 示例：

  {
    "orderId": "abbc4b57fb75",
    "paymentMethod": "APPLE_PAY",
    "deviceTag": "EUR"
  }
  

返回参数

成功响应

{
  "code": 0,
  "msg": "Payment info updated successfully",
  "orderId": "abbc4b57fb75"
}

失败响应

缺少 orderId

{
  "code": 400,
  "msg": "orderId is required"
}

订单不存在

{
  "code": 404,
  "msg": "Booking not found",
  "orderId": "abbc4b57fb75"
}

更新失败

{
  "code": 500,
  "msg": "Failed to update payment info",
  "orderId": "abbc4b57fb75"
}

响应字段说明

参数名称	类型	示例值	说明
code	Integer	0	系统状态码 0：成功 400：缺少必填参数（orderId） 404：订单不存在或不属于当前客户 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）

{
  "orderId": "abbc4b57fb75",
  "paymentMethod": "CREDIT_CARD",
  "creditCard": {
    "number": "4111111111111111",
    "CVV": "123",
    "expiryMonth": "12",
    "expiryYear": "25",
    "lastName": "Doe",
    "firstName": "John",
    "country": "US"
  }
}

响应（Response）

{
  "code": 0,
  "msg": "Payment info updated successfully",
  "orderId": "abbc4b57fb75"
}

使用 Apple Pay 并指定设备标签

请求（Request）

{
  "orderId": "abbc4b57fb75",
  "paymentMethod": "APPLE_PAY",
  "deviceTag": "EUR"
}

响应（Response）

{
  "code": 0,
  "msg": "Payment info updated successfully",
  "orderId": "abbc4b57fb75"
}

缺少 orderId 的错误请求

请求（Request）

{
  "paymentMethod": "CREDIT_CARD"
}

响应（Response）

{
  "code": 400,
  "msg": "orderId is required"
}

订单不存在的错误请求

请求（Request）

{
  "orderId": "nonexistent-order-id",
  "paymentMethod": "CREDIT_CARD"
}

响应（Response）

{
  "code": 404,
  "msg": "Booking not found",
  "orderId": "nonexistent-order-id"
}

错误码说明

错误码	说明	处理建议
0	成功	支付信息已成功更新
400	请求参数错误	检查是否提供了必填的 orderId
404	订单不存在	确认订单 ID 是否正确，且订单属于当前客户
500	服务器内部错误	系统处理异常，请稍后重试或联系技术支持