fengketrade/doc/建行生活API接口文档.md

# 建行生活API接口文档

> 文档版本: v1.1.6
> 生成时间: 2025-01-21
> 来源: 建行生活输入通讯报文v1.1.6【最新】.xlsx

---

## 📑 目录

- [1. 修订记录](#1-修订记录)
- [2. 接口规范](#2-接口规范)
  - [2.1 公共报文头](#21-公共报文头)
  - [2.2 通讯地址](#22-通讯地址)
  - [2.3 接口索引](#23-接口索引)
- [3. 核心接口](#3-核心接口)
  - [3.1 A3341TP01 - 服务方订单推送](#31-a3341tp01---服务方订单推送)
  - [3.2 A3341TP02 - 服务方订单更新](#32-a3341tp02---服务方订单更新)
  - [3.3 A3341TP03 - 服务方订单查询](#33-a3341tp03---服务方订单查询)
  - [3.4 A3341TP04 - 服务方订单退款](#34-a3341tp04---服务方订单退款)
  - [3.5 A3341TP05 - 订单支付权益查询](#35-a3341tp05---订单支付权益查询)
  - [3.6 A3341TP13 - 服务方订单补充信息](#36-a3341tp13---服务方订单补充信息)

---

## 1. 修订记录

| 修订日期 | 修订内容 | 上线状态 |
|---------|---------|----------|
| 2021-11-22 | 接口增加字段PLAT_MCT_ID、增加退款和订单查询接口 | 已上线 |
| 2022-11-11 | 增加订单子系统新接口 | 已上线 |
| 2023-03-28 | 订单推送新增GOODS_NM/PLATFORM_POINT两个字段 | 已上线 |
| 2024-01-24 | 修改报文顺序、内容 | 已上线 |
| 2024-02-23 | 订单更新新增PLATFORM_POINT、PAY_MODE、GOODS_NM字段 | 已上线 |
| 2024-02-26 | 增加权益信息查询接口 | 已上线 |
| 2025-06-09 | 增加SKU_LIST字段 | 待上线 |

---

## 2. 接口规范

### 2.1 公共报文头

#### 请求体（CLD_HEADER）

| 栏位项目名称 | 中文名称 | 栏位属性 | 必须 | 数据项说明 |
|------------|---------|---------|------|------------|
| CLD_TX_CHNL | 通讯渠道号 | C | Y | 跟svcid相同，YS44开头的字符串 |
| CLD_TX_TIME | 通讯时间 | C | Y | yyyyMMddHHmmss（请求通讯时间） |
| CLD_TX_CODE | 服务ID | C | Y | 如A3341TP01 |
| CLD_TX_SEQ | 全局事件流水号 | C | Y | 唯一流水号 |

#### 响应体（CLD_HEADER）

| 栏位项目名称 | 中文名称 | 栏位属性 | 必须 | 数据项说明 |
|------------|---------|---------|------|------------|
| CLD_TX_CHNL | 通讯渠道号 | C | Y | 跟svcid相同，YS44开头的字符串 |
| CLD_TX_TIME | 通讯时间 | C | Y | yyyyMMddHHmmss（响应通讯时间） |
| CLD_TX_CODE | 服务ID | C | Y | 如A3341TP01 |
| CLD_TX_SEQ | 全局事件流水号 | C | Y | 唯一流水号 |
| CLD_CODE | 响应码 | C | Y | 详见响应字典 |
| CLD_DESC | 响应描述 | C | N | 响应描述信息 |

### 2.2 通讯地址

#### UAT 测试环境
```
http://128.192.179.60/uat_new/tp_service/txCtrl/server?txcode=XX
```

#### 生产环境
```
https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=XX
```

> **注意**: XX 为服务ID，每个接口不同

#### 接口地址示例

| 接口 | 服务ID | 完整URL |
|------|--------|---------|
| 订单推送 | A3341TP01 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01 |
| 订单更新 | A3341TP02 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02 |
| 订单查询 | A3341TP03 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03 |
| 订单退款 | A3341TP04 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04 |
| 权益查询 | A3341TP05 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05 |
| 订单补充信息 | A3341TP13 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13 |

> **提示**: 当调用接口出现404时，请求头中加上：
> - `Accept: application/json`
> - `Content-Type: application/json`

### 2.3 接口索引

| 服务码 | 服务名称 | 服务类型 | 版本 | 备注 |
|--------|---------|---------|------|------|
| A3341TP01 | 服务方订单推送 | 直接调用 | 01 | 新接口 |
| A3341TP02 | 服务方订单更新 | 直接调用 | 01 | 新接口 |
| A3341TP03 | 服务方订单查询 | 直接调用 | 01 | 新接口 |
| A3341TP04 | 服务方订单退款 | 直接调用 | 01 | 新接口 |
| A3341TP05 | 订单支付权益查询 | 直接调用 | 01 | 新接口 |
| A3341TP13 | 服务方订单补充信息 | 直接调用 | 01 | 新接口 |

---

## 3. 核心接口

### 3.1 A3341TP01 - 服务方订单推送

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP01 |
| **服务名称** | 服务方订单推送 |
| **服务类型** | 直接调用 |
| **功能描述** | 用户在服务方下单成功后推送，支付时会校验订单信息 |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01 |

#### 请求参数（CLD_BODY）

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| USER_ID | 客户编号 | varChar(30) | Y | 建行生活的会员编号 |
| ORDER_ID | 订单编号 | varChar(30) | Y | 用户订单号，建行生活订单列表展示的订单订单号（对应收银台USER_ORDERID字段，支付时会校验订单信息） |
| ORDER_DT | 订单日期 | Char(14) | Y | yyyyMMddHHmmss |
| TOTAL_AMT | 订单原金额 | number(15,2) | Y | 第三方原始金额 |
| PAY_AMT | 订单实际支付金额 | number(15,2) | N | 支付网关支付金额。此处如果为空必须在状态变更时推送 |
| DISCOUNT_AMT | 第三方平台优惠金额 | number(15,2) | N | 第三方平台优惠金额。此处如果为空必须在状态变更时推送 |
| DISCOUNT_AMT_DESC | 第三方平台优惠定义 | varChar(1000) | N | 各金额之和等于第三方平台优惠金额，格式：名称=金额\|@\|名称=金额 |
| ORDER_STATUS | 订单状态 | Char(1) | Y | 0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消 |
| REFUND_STATUS | 退款状态 | Char(1) | Y | 0-无退款 1-退款申请 2-已退款 3-部分退款 |
| INV_DT | 订单过期日期 | Char(14) | N | yyyyMMddHHmmss |
| MCT_NM | 商户名称 | varChar(218) | Y | 商户名称 |
| CUS_ORDER_URL | 自定义订单链接 | varChar(256) | N | 订单详情地址(需要推送完整的订单详情URL) |
| OCC_MCT_LOGO_URL | 服务方商户logo图片地址 | varChar(512) | N | 必须以http://或https://开头 |
| PAY_FLOW_ID | 支付流水号 | varChar(30) | Y | 支付流水号，调用收银台时上送的支付流水号（对应收银台ORDERID字段） |
| PAY_USER_ID | 支付客户编号 | varChar(30) | N | 支付客户编号 |
| TOTAL_REFUND_AMT | 累计退款金额 | number(15,2) | N | 若支持多次退款，此次推送的金额为多次退款累计已退金额 |
| PREFTL_MRCH_ID | 门店商户号 | varChar(50) | N | 999的门店商户号，商户终端对应的建行生活门店编号 |
| PAY_MRCH_ID | 支付商户号 | Char(15) | Y | 调用收银台时上送的商户号 |
| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
| OCCCOUP_DISCOUNT_AMT | 建行专属优惠金额 | number(15,2) | N | 第三方平台的建行专属优惠金额 |
| OCCCOUP_DISCOUNT_AMT_DESC | 建行专属优惠定义 | varChar(1000) | N | 格式：券实例号=金额\|@\|券实例号=金额 |
| SPECIAL_STATUS | 特殊附加状态 | Char(5) | N | P0000-正常状态 P0001-待使用 P0002-待审核 P0003-已支付 P0004-待退款 P0005-退款中 P0006-待发货 P0007-已发货 P0008-进行中 P0009-预定中 P0010-预定成功 P0011-预定失败 P0012-已入住 P0013-已离店 P0014-未入住 P0015-配送中 P0016-出券中 |
| PLAT_ORDER_TYPE | 服务方订单类型 | Char(5) | N | T0000-普通类型 T0001-洗车 T0002-加油 T0003-停车 T0004-修车 T0005-充电 T0006-年检代办 T0007-道路救援 T0008-云南中石油充值 |
| GOODS_NM | 商品名称 | varChar(200) | N | 用户购买商品名称 |
| PLATFORM_POINT | 积分值 | number(15,2) | N | 订单使用积分抵扣积分值 |
| PAY_MODE | 支付方式 | varChar(8) | N | STSL-刷脸 STSK-刷卡 |
| PLATFORM | 下单场景 | Char(2) | N | 99-建行生活APP 98-微应用 |
| **SKU_LIST** | **商品信息** | **varchar(3000)** | **N** | **商品信息列表(JSON字符串)，商品售价SKU_SELL_PRICE不能大于商品定价SKU_REF_PRICE** |

#### SKU_LIST 字段说明（JSON数组）

```json
[
  {
    "SKU_NAME": "商品名称",
    "SKU_REF_PRICE": 15.01,
    "SKU_NUM": 1,
    "SKU_SELL_PRICE": 10.01
  },
  {
    "SKU_NAME": "商品名称2",
    "SKU_REF_PRICE": 15.01,
    "SKU_NUM": 2,
    "SKU_SELL_PRICE": 10.01
  }
]
```

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| SKU_NAME | 商品名称 | varChar | Y | 商品名称 |
| SKU_REF_PRICE | 商品参考价 | number(15,2) | Y | 商品参考价，支持两位小数 |
| SKU_NUM | 商品数量 | number(11,2) | Y | 商品数量 |
| SKU_SELL_PRICE | 商品单价 | number(15,2) | Y | 商品单价，支持两位小数 |

#### 响应参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| CCB_DISCOUNT_AMT | 建行支付侧优惠金额 | number(15,2) | N | 因业务调整，后续下线字段 |
| CCB_DISCOUNT_AMT_DESC | 建行支付侧优惠定义 | varChar(1000) | N | 因业务调整，后续下线字段 |

---

### 3.2 A3341TP02 - 服务方订单更新

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP02 |
| **服务名称** | 服务方订单更新 |
| **服务类型** | 直接调用 |
| **功能描述** | 在用户订单状态有变动时调用，比如电影出票成功、外卖配送中等 |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02 |
| **重要说明** | 通知类型为"支付状态修改"时，支付状态不能为空，退款状态为空；通知类型为"退款状态修改"时，退款状态不能为空，支付状态为空 |

#### 请求参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| ORDER_ID | 订单编号 | varChar(30) | Y | 用户订单号（对应收银台USER_ORDERID字段） |
| INFORM_ID | 通知类型 | Char(1) | Y | 0-支付状态修改 1-退款状态修改 |
| PAY_STATUS | 支付状态 | Char(1) | N | 0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消 |
| REFUND_STATUS | 退款状态 | Char(1) | N | 0-无退款 1-退款申请 2-已退款 3-部分退款 |
| PAY_AMT | 订单实际支付金额 | number(15,2) | N | 订单实际支付金额 |
| DISCOUNT_AMT | 第三方平台优惠金额 | number(15,2) | N | 第三方平台优惠金额 |
| DISCOUNT_AMT_DESC | 第三方平台优惠定义 | varChar(1000) | N | 格式：名称=金额\|@\|名称=金额 |
| CUS_ORDER_URL | 自定义订单链接 | varChar(256) | N | 订单详情地址(需要推送完整的订单详情URL) |
| OCC_MCT_LOGO_URL | 服务方商户logo图片地址 | varChar(512) | N | http:// 或 https:// 为起始 |
| PAY_FLOW_ID | 支付流水号 | varChar(30) | Y | 调用收银台时上送的支付流水号（对应收银台ORDERID字段） |
| PAY_USER_ID | 支付客户编号 | varChar(150) | N | 支付客户编号 |
| TOTAL_REFUND_AMT | 累计退款金额 | number(15,2) | N | 若支持多次退款，此次推送的金额为多次退款累计已退金额 |
| PREFTL_MRCH_ID | 门店商户号 | varChar(50) | N | 999的门店商户号 |
| PAY_MRCH_ID | 支付商户号 | Char(15) | Y | 调用收银台时上送的商户号 |
| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
| OCCCOUP_DISCOUNT_AMT | 建行专属优惠金额 | number(15,2) | N | 第三方平台的建行专属优惠金额 |
| OCCCOUP_DISCOUNT_AMT_DESC | 建行专属优惠定义 | varChar(1000) | N | 格式：券实例号=金额\|@\|券实例号=金额 |
| SPECIAL_STATUS | 特殊附加状态 | Char(5) | N | 同订单推送 |
| PLAT_ORDER_TYPE | 服务方订单类型 | Char(5) | N | 同订单推送 |
| GOODS_NM | 商品名称 | varChar(200) | N | 用户购买商品名称 |
| PLATFORM_POINT | 积分值 | number(15,2) | N | 订单使用积分抵扣积分值 |
| PAY_MODE | 支付方式 | varChar(8) | N | STSL-刷脸 STSK-刷卡 |
| PLATFORM | 下单场景 | Char(2) | N | 99-建行生活APP 98-微应用 |
| SKU_LIST | 商品信息 | varchar(3000) | N | 商品信息列表(JSON字符串)，格式同订单推送 |

#### 响应参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| IS_SUCCESS | 是否更新成功 | Char(1) | Y | 0-否 1-是 |
| CCB_DISCOUNT_AMT | 建行支付侧优惠金额 | number(15,2) | N | 因业务调整，后续下线字段 |
| CCB_DISCOUNT_AMT_DESC | 建行支付侧优惠定义 | varChar(1000) | N | 因业务调整，后续下线字段 |

---

### 3.3 A3341TP03 - 服务方订单查询

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP03 |
| **服务名称** | 服务方订单查询 |
| **服务类型** | 直接调用 |
| **功能描述** | 订单主动查询，在未收到支付结果通知时使用。查询结果存在延时情况，接口返回未查到可以适当重复查询 |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03 |
| **流控限制** | 默认流控值为 100/TPM |

#### 请求参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| TX_TYPE | 交易类型 | varChar(1) | Y | 0-支付交易 1-退款交易 a-查询可退款的订单 |
| TXN_PRD_TPCD | 查询时间范围类型 | varChar(2) | Y | 99-自定义时间段查询 |
| STDT_TM | 开始日期时间 | Char(14) | N | 查询时间范围类型为99时必输，格式yyyyMMddhhmiss |
| EDDT_TM | 结束日期时间 | Char(14) | N | 查询时间范围类型为99时必输，格式yyyyMMddhhmiss |
| ONLN_PY_TXN_ORDR_ID | 订单编号 | varChar(60) | N | 调用收银台时支付流水号，对应字段ORDERID |
| SCN_IDR | 场景标识 | varChar(3) | N | BHK-本行卡 THK-他行卡 ZFB-支付宝 CFT-微信 |
| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
| POS_CODE | 柜台号 | varChar(9) | N | 柜台号 |
| POS_ID | POS终端编号 | varChar(19) | N | POS终端编号 |
| TXN_STATUS | 交易状态 | varChar(2) | Y | 00-交易成功 01-交易失败 02-不确定 |
| MSGRP_JRNL_NO | 商户的流水号 | varChar(60) | N | 商户支付流水号或者退款流水号 |
| PAGE | 当前页次 | number(10) | Y | 当前页次 |

#### 响应参数（摘要）

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| CUR_PAGE | 当前页次 | number(10) | N | 每页最多返回10条记录 |
| PAGE_COUNT | 总页次 | number(10) | N | 总页次 |
| ED_CRD_PRTY_IDR_CD | 商户号 | varChar(15) | N | 商户号 |
| PY_AMT | 支付金额 | number(16,2) | N | 单位：元 |
| MRCH_RFND_AMT | 商户退款金额 | number(16,2) | N | 单位：元 |
| LIST | 订单列表 | Array | N | 订单详情列表（见下表） |

#### LIST 数组字段（订单列表）

| 字段名 | 中文名称 | 数据类型 | 说明 |
|--------|---------|----------|------|
| ONLN_PY_TXN_ORDR_ID | 订单编号 | varChar(120) | 订单编号 |
| CLRG_STM_DT_TM | 交易时间 | varChar(14) | 格式yyyyMMddhhmiss |
| ACQ_FNDS_CLRG_DT | 记账日期 | varChar(8) | 格式yyyyMMdd |
| ORDR_TM | 原支付订单时间 | varChar(42) | 格式yyyyMMddhhmiss |
| AHN_TXNAMT | 交易金额 | number(16,2) | 单位：元 |
| ORDR_PYRFD_AMT | 退款总额 | number(16,2) | 单位：元 |
| TXN_CLRGAMT | 结算金额 | number(16,2) | 单位：元 |
| MRCHCMSN_AMT | 手续费金额 | number(16,2) | 单位：元 |
| ORIG_AMT | 订单金额 | number(16,2) | 单位：元 |
| DISCOUNT_AMT | 优惠金额 | number(16,2) | 订单金额-交易金额=优惠金额 |
| RETGDS_ORIG_TXNAMT | 原支付金额 | number(16,2) | 单位：元 |
| CST_ACCNO | 支付卡号 | varChar(32) | 支付卡号 |
| CCYCD | 币种 | varChar(3) | 币种 |
| TXN_STATUS | 交易状态 | varChar(2) | 00-成功 01-失败 02/04-不确定 TO-超时 |
| ORIOVRLSTTNEV_TRCK_NO | 银行流水号 | varChar(25) | 银行流水号 |
| MSGRP_JRNL_NO | 商户流水号 | varChar(240) | 退款时商户上送的退款流水号 |
| PAY_MODE | 支付方式 | Char(3) | BHK-建行 THK-他行 ZFB-支付宝 CFT-微信 |

> **更多字段请参考Excel原文档**

---

### 3.4 A3341TP04 - 服务方订单退款

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP04 |
| **服务名称** | 服务方订单退款 |
| **服务类型** | 直接调用 |
| **功能描述** | 订单退款时使用。在退款结果未返回结果时，建议先查询退款结果再做后续处理 |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04 |

#### 请求参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
| MONEY | 退款金额 | number(16,2) | Y | 单位：元 |
| ORDER | 订单号 | varChar(30) | Y | 调用收银台时支付流水号，对应字段ORDERID |
| STDT_TM | 开始日期时间 | Char(14) | Y | 根据支付时间往前加4小时，格式yyyyMMddhhmiss |
| EDDT_TM | 结束日期时间 | Char(14) | Y | 根据支付时间往后加4小时，但日期不能超过当前日期，格式yyyyMMddhhmiss |
| REFUND_CODE | 退款流水号 | varChar(30) | N | 可不填，商户可根据需要填写，退款流水号由商户的系统生成（在未收到退款接口返回时，可用此字段查询退款结果） |

#### 响应参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| ORDER_NUM | 订单号 | varChar(30) | Y | 订单号 |
| PAY_AMOUNT | 支付金额 | number(16,2) | Y | 单位：元 |
| AMOUNT | 退款金额 | number(16,2) | Y | 单位：元 |
| Cst_AccNo | 客户账户 | varChar(32) | N | 脱敏后客户退款账号 |

---

### 3.5 A3341TP05 - 订单支付权益查询

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP05 |
| **服务名称** | 订单支付权益查询 |
| **服务类型** | 直接调用 |
| **功能描述** | 查询订单支付时使用的权益信息。此接口跟订单支付结果一起计算流控TPM |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05 |

#### 请求参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号（暂不支持） |
| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
| TX_SPECIAL_EC | 交易类型 | varChar(1) | Y | 0-支付交易 1-退款交易 |
| ORDER_ID | 订单号 | varChar(30) | Y | 调用收银台时支付流水号，对应字段ORDERID |
| OriOvrlsttnEV_Trck_No | 原银行流水号 | varChar(25) | N | 原银行流水号 |
| Txn_Prd_TpCd | 交易期间类型代码 | varChar(2) | N | 08-1个小时内，送空则为08 |
| POS_ID | 终端号 | varChar(19) | N | 终端号 |
| Jrnl_TpCd | 流水类型代码 | varChar(2) | N | XM-数字人民币 PT-普通收单 YH-单纯查券优惠 AL-全部，送空则为YH |

#### 响应参数（摘要）

| 字段名 | 中文名称 | 数据类型 | 说明 |
|--------|---------|----------|------|
| Py_Amt | 总支付金额 | varChar(19) | 总支付金额 |
| Mrch_Rfnd_Amt | 总退款金额 | varChar(10) | 总退款金额 |
| Py_Ordr_Amt | 总支付订单金额 | varChar(18) | 总支付订单金额 |
| Rght_Cgy_Inf | 权益类信息 | varChar(3000) | 权益信息（见下方说明） |
| LIST | 订单列表 | Array | 订单详情列表 |

#### Rght_Cgy_Inf 权益类信息说明

权益位图格式示例：
```
P6:{FL3:有价折扣券,AM1:30.00,AM2:30.00},P3:{FL2:02,FL3:满减活动,AM1:30.00,AM2:30.00}
```

**字段说明**:
- P6: 商户券
- FL1: 优惠度量（如积分数、券数量）
- FL2: 清算方式（01-后结算 02-在线一笔清算 03-在线异步清算）
- FL3: 优惠类型（如满减活动、满减券、有价券等）
- FL4: 优惠名称（如活动描述或券名称）
- AM1: 优惠金额
- AM2: 清算金额
- AM3: 银行出资金额
- AM4: 商户出资金额
- AM5: 优惠券面额
- AM6: 客户实付金额
- AM7: 积分抵扣金额

**P6 优惠券类型**:
- 免费折扣券
- 免费代金券
- 免费实物券
- 免费定额券
- 有价折扣券
- 有价代金券
- 有价实物券
- 有价定额券

---

### 3.6 A3341TP13 - 服务方订单补充信息

#### 接口说明

| 项目 | 说明 |
|------|------|
| **服务码** | A3341TP13 |
| **服务名称** | 服务方订单补充信息 |
| **服务类型** | 直接调用 |
| **功能描述** | 补充订单的商品信息（SKU_LIST） |
| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13 |

#### 请求参数

| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
|--------|---------|----------|------|------|
| USER_ID | 会员编号 | varChar(40) | Y | 会员编号 |
| ORDER_ID | 订单编号 | varChar(40) | Y | 订单编号 |
| SKU_LIST | 商品信息列表 | varChar(3000) | N | 商品信息列表(JSON字符串)，格式同订单推送接口 |

#### SKU_LIST 字段说明

同订单推送接口的 SKU_LIST 字段，包含：
- SKU_NAME：商品名称
- SKU_REF_PRICE：商品参考价
- SKU_NUM：商品数量
- SKU_SELL_PRICE：商品单价

⚠️ **重要提示**：商品售价 SKU_SELL_PRICE 不能大于商品定价 SKU_REF_PRICE，字段长度为字节，注意中文字段长度。

---

## 附录

### A. 订单状态枚举

#### 订单状态（ORDER_STATUS / PAY_STATUS）
- `0` - 待支付
- `1` - 支付成功
- `2` - 已过期
- `3` - 支付失败
- `4` - 取消

#### 退款状态（REFUND_STATUS）
- `0` - 无退款
- `1` - 退款申请
- `2` - 已退款
- `3` - 部分退款

#### 特殊附加状态（SPECIAL_STATUS）
- `P0000` - 正常状态
- `P0001` - 待使用
- `P0002` - 待审核
- `P0003` - 已支付
- `P0004` - 待退款
- `P0005` - 退款中
- `P0006` - 待发货
- `P0007` - 已发货
- `P0008` - 进行中
- `P0009` - 预定中
- `P0010` - 预定成功
- `P0011` - 预定失败
- `P0012` - 已入住
- `P0013` - 已离店
- `P0014` - 未入住
- `P0015` - 配送中
- `P0016` - 出券中

### B. 服务方订单类型（PLAT_ORDER_TYPE）
- `T0000` - 普通类型
- `T0001` - 洗车
- `T0002` - 加油
- `T0003` - 停车
- `T0004` - 修车
- `T0005` - 充电
- `T0006` - 年检代办
- `T0007` - 道路救援
- `T0008` - 云南中石油充值

### C. 支付方式（PAY_MODE / Scn_Idr）
- `STSL` - 刷脸
- `STSK` - 刷卡
- `BHK` - 本行卡
- `THK` - 他行卡
- `ZFB` - 支付宝
- `CFT` - 微信

### D. 交易状态（TXN_STATUS / Txn_Status）
- `00` - 交易成功
- `01` - 交易失败
- `02` - 不确定
- `04` - 不确定（前端无须发冲正）
- `TO` - 交易超时

---

## 开发指南

### 1. 接口调用流程

```
1. 构建公共报文头（CLD_HEADER）
   ├── CLD_TX_CHNL：服务方ID（如YS44000009001853）
   ├── CLD_TX_TIME：当前时间（YmdHis格式）
   ├── CLD_TX_CODE：服务码（如A3341TP01）
   └── CLD_TX_SEQ：唯一流水号

2. 构建业务参数（CLD_BODY）
   └── 根据具体接口填充业务参数

3. 整体报文加密
   ├── 将CLD_HEADER + CLD_BODY转JSON
   ├── 使用建行公钥RSA加密
   └── 生成MD5签名（mac字段）

4. 发送HTTP POST请求
   ├── URL：基础地址 + ?txcode=服务码
   ├── 参数：cnt（加密内容）、mac（签名）
   └── 请求头：Content-Type: application/x-www-form-urlencoded

5. 处理响应
   ├── 使用商户私钥解密响应cnt字段
   ├── 验证响应mac签名
   └── 解析CLD_HEADER和CLD_BODY
```

### 2. 重要提示

⚠️ **密钥管理**
- 商户私钥：用于解密建行返回的数据
- 商户公钥：参与支付串的MD5签名计算
- 建行公钥：用于加密发送给建行的数据

⚠️ **字段校验**
- SKU_SELL_PRICE（商品售价）不能大于 SKU_REF_PRICE（商品定价）
- 通知类型为"支付状态修改"时，PAY_STATUS 必填，REFUND_STATUS 为空
- 通知类型为"退款状态修改"时，REFUND_STATUS 必填，PAY_STATUS 为空

⚠️ **流控限制**
- 订单查询接口（A3341TP03）：默认流控值为 100/TPM
- 权益查询接口（A3341TP05）：与订单支付结果一起计算流控TPM

⚠️ **时间格式**
- 所有时间字段统一使用：`yyyyMMddHHmmss` 格式
- 示例：`20250121120000`

### 3. 错误处理

- 接口返回404：请在请求头中添加 `Accept: application/json` 和 `Content-Type: application/json`
- 查询结果延时：订单查询接口存在延时，返回未查到时可适当重复查询
- 退款未返回：建议先调用订单查询接口查询退款结果，再做后续处理

---

**文档结束**