# 建行生活API接口文档

> 文档版本: v2.0.0
> 更新时间: 2025-10-21
> 来源:
> - 建行生活输入通讯报文v1.1.6【最新】.xlsx
> - 建行生活原生与h5交互规范接口1.3（新）.html
> - 建行相关App服务方接入文档v2.20_20250725.html

---

## 📑 目录

- [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---服务方订单补充信息)
- [4. H5 与原生交互接口（JS Bridge）](#4-h5-与原生交互接口js-bridge)
  - [4.1 交互规范说明](#41-交互规范说明)
  - [4.2 callCamera - 调用相机/相册](#42-callcamera---调用相机相册)
  - [4.3 getPosition - 获取定位](#43-getposition---获取定位)
- [5. 服务方接入规范](#5-服务方接入规范)
  - [5.1 跳转 URL 规范](#51-跳转-url-规范)
  - [5.2 建行相关 App 环境识别](#52-建行相关-app-环境识别)
  - [5.3 收银台调用方法](#53-收银台调用方法)
  - [5.4 商户下单支付参数定义（完整）](#54-商户下单支付参数定义完整)
  - [5.5 支付成功页面回调设置](#55-支付成功页面回调设置)
  - [5.6 其他说明](#56-其他说明)
- [6. 报文规范与加密](#6-报文规范与加密)
  - [6.1 报文结构](#61-报文结构)
  - [6.2 报文加密及签名](#62-报文加密及签名)
- [7. 回调通知接口](#7-回调通知接口)
  - [7.1 建行生活支付通知接口](#71-建行生活支付通知接口)
  - [7.2 建行生活退款操作通知接口](#72-建行生活退款操作通知接口)

---

## 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字段 | 待上线 |
| 2025-10-21 | **整合多个文档**：新增 H5 与原生交互接口（JS Bridge）、服务方接入规范、报文加密与签名、回调通知接口等章节 | 文档整合 |

---

## 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 | 因业务调整，后续下线字段 |

#### 报文示例

##### 1. 明文报文（加密前）

```json
{
  "CLD_HEADER": {
    "CLD_TX_CHNL": "YS44000009001853",
    "CLD_TX_TIME": "20250121143522",
    "CLD_TX_CODE": "A3341TP01",
    "CLD_TX_SEQ": "PAY20250121143522123456"
  },
  "CLD_BODY": {
    "USER_ID": "CCB_USER_12345678",
    "ORDER_ID": "SO202501211435220001",
    "ORDER_DT": "20250121143500",
    "TOTAL_AMT": "100.00",
    "PAY_AMT": "90.00",
    "DISCOUNT_AMT": "10.00",
    "DISCOUNT_AMT_DESC": "满减优惠=10.00",
    "ORDER_STATUS": "0",
    "REFUND_STATUS": "0",
    "INV_DT": "20250121173500",
    "MCT_NM": "丰科贸易(荷西嘉园店)",
    "CUS_ORDER_URL": "https://example.com/order/detail?id=123",
    "OCC_MCT_LOGO_URL": "https://example.com/logo.png",
    "PAY_FLOW_ID": "PAY20250121143522123456",
    "PAY_MRCH_ID": "105003953998037",
    "GOODS_NM": "测试商品",
    "PLATFORM": "99",
    "SKU_LIST": "[{\"SKU_NAME\":\"测试商品\",\"SKU_REF_PRICE\":100.00,\"SKU_NUM\":1,\"SKU_SELL_PRICE\":90.00}]"
  }
}
```

##### 2. 加密报文（最终发送）

**报文结构**：
```json
{
  "cnt": "BASE64加密后的明文内容...",
  "mac": "32位小写MD5签名",
  "svcid": "YS44000009001853"
}
```

**字段说明**：

| 字段 | 说明 |
|------|------|
| cnt | 使用服务方公钥对明文报文进行RSA加密后的BASE64编码内容 |
| mac | MD5(明文报文 + 服务方私钥) 的32位**大写**签名（API接口使用大写） |
| svcid | 服务方编号（建行分配） |

**请求方式**：
```http
POST https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01
Content-Type: application/json; charset=utf-8

{"cnt":"BASE64加密内容","mac":"大写MD5签名","svcid":"服务方编号"}
```

**完整示例**（参考 - 来自建行提供的示例文件）：
```json
{
  "cnt": "Y2tFMDFJd2RGMGg5aFdXUGtjVVdaSmo4NHBKQzNNZE1wQTRRSXZVRlhBSWhqVEdXNE1LcE9MOXdxY0hhNUlIZndUU0RLK3NrZ1hpTytJUitpREEwSUp0bktRcWMxRG5hN1R0OEtjcUkxTUFDVE5FY2Z0b3lCeTVTaEo3cmNjSnBOUVFsSjRBR2htSzRheEhNb0p6N215eFViK1ZjeGd5WjVTTjJQcHUxQlBnZXJsQXE2Q1lrQ2VuSmZEYUxVSks5RGx2Yk9YWDlDczJiVVllYjlHSHQrUkFuYTljc2hucGhqVWNwNDgrcThNcGhQOElBL20xNVk5NG9lZEV4SXpmc0pDcDExZjFvQ0E5YkwwOWJOZjM4VHR3TkJkTmhqM3lKSVpWeWVpT0FucGhjS3JpOEs5RnlZbXlNVHF1UER3UjhmQ0p5dk5vYkNMS1BPRmQ3WFdXTVczZ29kSWpLaG5OUnhnaFA3N2txdDU3K2Rkd3hGbDgxUEdYbXJWN1ZKWDFOeXRVUFg2dWp3ZzdsUU1OSTlubU1kVE9nbHZJUHRoS205aEludFc2ZFBVTG1DUlNLNzZDc05qTUIyb1hTR2M2cHBNazMxNDJSa05KR0hvY1ZBNFUzcmc4SVk4ZFlYaTUzZmF3cHRES3pHY2JYVFI0SldRVzRNU2ZmSUxvNFpxTkY=",
  "mac": "947CAB4DFEBE59265DD28246E4465157",
  "svcid": "YSTEST"
}
```

**⚠️ 重要说明**：
- 请求体必须是**JSON格式**，不是URL编码格式
- MAC签名必须是**32位大写MD5**（API接口）
- Content-Type必须设置为`application/json; charset=utf-8`

---

### 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`
- 查询结果延时：订单查询接口存在延时，返回未查到时可适当重复查询
- 退款未返回：建议先调用订单查询接口查询退款结果，再做后续处理

---

## 4. H5 与原生交互接口（JS Bridge）

> 版本: v1.1
> 来源: 建行生活原生与h5交互规范接口1.3（新）.html

### 4.1 交互规范说明

#### 4.1.1 H5 请求 JS Bridge API 格式

用于 H5 调用由 Native 提供的 js api 能力，如扫一扫、定位、登录等能力。

**调用格式：**

```javascript
// H5 请求
/**
 * H5 与 native api 交互
 * service: api类型
 * action: api名称
 * params: 参数
 * callBack: 回调方法名，H5自定义，通过变量的方式传递到客户端，供客户端执行指令后回调
 */
CCBMofeBridge.exec(service, action, params, callBackTmp)
```

**Native 回调格式：**

```javascript
// native 回调 callBackTmp 格式定义
/**
 * 客户端回调 H5 调用的 js 方法示例
 * data: 返回的数据，json格式
 * status: 返回状态，0：成功，1:失败，-2:功能未开通
 */
callBackTmp('{
    "data":"",     // jsonStr api响应字典转Json
    "status":"0",  // 状态码
}')
```

---

### 4.2 callCamera - 调用相机/相册

#### 接口说明

调用手机相机拍照或选择相册图片。

#### 请求参数

| 字段名 | 类型 | 默认值 | 必填 | 说明 |
|--------|------|--------|------|------|
| sourceType | string | - | 是 | `album` 相册 / `camera` 拍照 |
| maxSize | string | - | 否 | 图片最大大小，单位为 k |
| count | string | 1 | 否 | 最多可以选择的图片张数，目前仅建行生活支持，仅调用相册时支持 |

#### 成功返回参数

| 字段名 | 类型 | 说明 |
|--------|------|------|
| imgs | array | 图片 base64 串数组 |

#### 错误返回参数

| 字段名 | 类型 | 说明 |
|--------|------|------|
| errCode | string | 错误码：`1014` 用户未授权，`0001` 参数错误，`-1` 用户取消 |
| errMsg | string | 错误信息 |

#### 调用示例

```javascript
var param = {
    "sourceType": "album",
    "maxSize": "1024",
    "count": "2"
}
function callback(res) {
    console.log(res);
}
window.callback = callback
window.CCBMofeBridge.exec("baseAPI", "callCamera", JSON.stringify(param), 'callback');
```

#### 响应示例

**成功响应：**

```json
{
    "data": {
        "imgs": ["data:image/png;base64,xxxxxxxx", "data:image/png;base64,xxxxxxxx"]
    },
    "status": "0"  // 0：成功，1:失败，-2:功能未开通
}
```

**失败响应：**

```json
{
    "data": {
        "errCode": "1014",
        "errMsg": "用户未授权"
    },
    "status": "1"
}
```

---

### 4.3 getPosition - 获取定位

#### 接口说明

获取用户当前位置信息。

#### 请求参数

| 字段名 | 类型 | 默认值 | 建行生活必填 | 手机银行必填 | 说明 |
|--------|------|--------|--------------|--------------|------|
| Can_Ahn_Inst | string | - | 否 | 是 | 机构号 |
| appName | string | - | 否 | 是 | 名称 |
| cdnLogoUrl | string | - | 否 | 否 | logoUrl 地址 |
| mode | string | 1 | 否 | 否 | 定位模式：<br>`0` 缓存优先，先返回上一次定位缓存再异步更新缓存<br>`1` 即时定位，loading等待即时定位后返回，并更新缓存（默认）<br>`2` 兜底定位，先实时定位，超时后返回缓存定位 |
| timeout | string | 2 | 否 | 否 | 定位 API 超时时间，默认值为 2s，支持通用技术参数配置，字段为 locationCacheTime |

#### 成功返回参数

| 字段名 | 类型 | 说明 |
|--------|------|------|
| cityName | string | 城市名称，如：广州市 |
| cityCode | string | 城市代码，如：440100 |
| latitude | string | 纬度 |
| longitude | string | 经度 |
| address | string | 地址 |
| adCode | string | 区域行政编码，如：440106 |
| gpsType | string | 坐标系，`bd09` 为百度，`gcj02` 为高德 |

#### 错误返回参数

| 字段名 | 类型 | 说明 |
|--------|------|------|
| gpsType | string | 坐标系，`bd09` 为百度，`gcj02` 为高德 |
| bizCode | string | 地图 sdk 原始定位结果错误码 |
| errCode | string | 错误码：<br>`1014` 用户未授权<br>`1016` 手机GPS开关未开启<br>`1017` 地图sdk返回失败<br>`0001` 参数错误 |
| errMsg | string | 错误信息 |

#### 调用示例

```javascript
var param = {}
function callback(res) {
    console.log(res);
}
window.callback = callback
window.CCBMofeBridge.exec("baseAPI", "getPosition", JSON.stringify(param), 'callback');
```

#### 响应示例

**成功响应：**

```json
{
    "data": {
        "gpsType": "bd09",
        "adCode": "440106",
        "address": "中国广东省广州市天河区猎德街道珠江新城华夏路10号",
        "cityCode": "440100",
        "cityName": "广州市",
        "latitude": "23.123691",
        "longitude": "113.329941"
    },
    "status": "0"
}
```

**失败响应：**

```json
{
    "data": {
        "gpsType": "bd09",
        "bizCode": "06",
        "errCode": "1017",
        "errMsg": "定位失败"
    },
    "status": "1"
}
```

---

## 5. 服务方接入规范

> 版本: v2.20
> 来源: 建行相关App服务方接入文档v2.20_20250725.html

### 5.1 跳转 URL 规范

建行相关 App 通过分类入口跳转或订单详情跳转至服务方链接时，使用 URL 格式为：

```
url?platform=ccblife&channel=mbs&ccbParamSJ=xxxxxx&CITYID=330100&USERCITYID=440100
```

**参数说明：**

- **url**: 服务方页面链接地址（一般为中间页面，用于对跳转参数的解密验签处理及二次跳转）
- **platform**: `ccblife` 为建行生活平台标识符
- **channel**: 当前运行环境所在的 App
  - `channel=mbs` 表示在中国建设银行 App 运行
  - 无此参数则默认为在建行生活 App 运行
- **CITYID**: 用户选择城市代码（6位中国城市代码）
- **USERCITYID**: 用户定位城市代码（6位中国城市代码）
- **ccbParamSJ**: 使用服务方公钥 RSA 加密后再 base64 + encodeURIComponent 的加密密文

#### ccbParamSJ 密文携带的参数

解密后明文格式为: `USERID=xxx&MOBILE=xxx...`（先进行 URLDecode 之后，再进行解密）

| 参数名 | 参数类型 | 中文名 | 备注 |
|--------|----------|--------|------|
| BGCOLOR | String | 背景色 | 默认为空 |
| PLATFLOWNO | String | 登录校验流水号 | |
| TIMESTAMP | String | 跳转服务方时间戳 | 13位毫秒级 |
| USERID | String | 建行生活用户ID | |
| MOBILE | String | 手机号码 | |
| CITYID | String | 用户选择城市代码 | 使用标准的中国城市代码 |
| USERCITYID | String | 用户定位城市代码 | |
| LGT | String | 经度 | |
| LTT | String | 纬度 | |
| GPS_TYPE | String | GPS坐标系 | `gcj02`（高德地图坐标）、`bd09`（百度地图坐标） |
| APPID | String | 小程序appid | 小程序专用参数，APP不存在 |
| OPENID | String | 用户在小程序下唯一标识 | 小程序专用参数，APP不存在 |
| ORDERID | String | 订单号 | 通过订单详情跳转会携带此字段 |
| TOKEN | String | 建行生活用户TOKEN | 仅通过手机银行访问建行生活场景时携带 |

#### 加密串验证建议

⚠️ **重要提示**：为防止加密串被非法窃取导致的越权风险，建议服务方对加密串进行唯一请求校验。

可选校验方案：
1. 使用 PLATFLOWNO 作为一次性令牌，使用后立即失效
2. 验证 TIMESTAMP 时间戳，拒绝超过一定时间（如5分钟）的请求
3. 结合 USERID 和 PLATFLOWNO 进行会话绑定

---

### 5.2 建行相关 App 环境识别

服务方生活场景，按本章节方法识别当前运行的 App 环境是否为建行相关 App。

#### 5.2.1 建行生活 App 环境判断

通过检测 URL 参数中的 `platform=ccblife` 和 `channel` 参数来判断：

```javascript
// 判断是否为建行生活 App
function isCCBLifeApp() {
    const urlParams = new URLSearchParams(window.location.search);
    const platform = urlParams.get('platform');
    const channel = urlParams.get('channel');

    return platform === 'ccblife' && !channel;
}
```

#### 5.2.2 中国建设银行 App 环境判断

通过检测 URL 参数中的 `channel=mbs` 来判断：

```javascript
// 判断是否为中国建设银行 App
function isCCBApp() {
    const urlParams = new URLSearchParams(window.location.search);
    const channel = urlParams.get('channel');

    return channel === 'mbs';
}
```

---

### 5.3 收银台调用方法

#### 5.3.1 在建行生活 App 环境收银台调用

##### (1) iPhone 系统调用

```javascript
// iOS 系统调用收银台
function callCashierIOS(paymentParams) {
    // paymentParams 为支付参数串
    window.location.href = 'ccbpayment://openCashier?params=' + encodeURIComponent(paymentParams);
}
```

##### (2) Android 系统调用

```javascript
// Android 系统调用收银台
function callCashierAndroid(paymentParams) {
    // paymentParams 为支付参数串
    window.CCBAndroid.callCashier(paymentParams);
}
```

#### 5.3.2 在中国建设银行 App 环境收银台调用

```javascript
// 在建设银行 App 中调用收银台
function callCashierInCCBApp(paymentParams) {
    window.CCBMofeBridge.exec("paymentAPI", "callCashier", paymentParams, 'paymentCallback');
}

function paymentCallback(result) {
    // 处理支付结果
    console.log('支付结果:', result);
}
```

---

### 5.5 支付成功页面回调设置

#### 5.5.1 回调地址设置方法

支付完成后默认跳转到建行生活的支付成功页面，如服务方需要跳转到自己的成功页，请调用 `setCache` 方法来设置。

⚠️ **重要提示**：`setCache` 操作须在调起收银台（5.3.1 在建行生活App环境收银台调用）**之前**进行。

**设置方法（仅在建行生活 App 环境有效）：**

```javascript
var requestObj = {
    action: 'setCache',  // 设置回调地址
    params: {
        key: '',   // 回调的 key，与下单参数的 remark2 保持一致，上送服务方编号
        value: ''  // 回调的 url，支付成功后将由建行生活收银台跳转至此 url
    }
}

window.CCBBridge.requestNative(JSON.stringify(requestObj), 'callBackName');

// 注：callBackName 是回调函数的名称（可自行定义），请先将回调函数挂载到 window 对象下
//     该回调仅作为地址设置成功的参考
```

**在中国建设银行 App 环境：**

在中国建设银行 App 环境需通过《5.4 商户下单支付参数定义》中的 **PAYSUCCESSURL** 参数提供支付成功页面 URL。

#### 5.5.2 回调 URL 携带参数

支付成功跳转后，设置的回调 URL 会增加携带如下参数：

| 字段名 | 中文名 | 备注 |
|--------|--------|------|
| MERCHANTID | 商户号 | |
| POSID | 柜台号 | |
| ORDERID | 订单号 | |
| PAYMENT | 订单金额 | |
| SUCCESS | 支付成功标识 | 固定为 Y |
| REMARK2 | 支付备注二 | |
| realPayment | 实付金额 | 优惠后实际支付的金额 |
| ccbParamSJ | 用户信息加密串 | 与跳转服务方携带的相同 |

⚠️ **重要提示**：最终支付结果请以服务器通知（7.1 建行生活支付通知接口）为准，前端回调仅作为页面跳转使用。

---

### 5.6 其他说明

#### 5.6.1 支付流程要点

1. **调起支付**：建行相关 App 根据订单信息调起支付
2. **完成支付**：在支付模块完成支付后，点击完成支付，关闭支付模块，跳转到支付成功页面
3. **结果确认**：⚠️ **支付成功结果最终以服务器通知为准**（参考 7.1 建行生活支付通知接口）

#### 5.6.2 业务流程说明

**以建行生活 App 环境为例（仅供参考）：**

**重点步骤说明：**

1. **步骤2 - 订单推送**：
   - 由服务方调用订单推送接口（**A3341TP01**）向建行生活推送订单信息
   - 参考《3.1 A3341TP01 - 服务方订单推送》

2. **步骤3 - 调用收银台**：
   - 参考《5.3 收银台调用方法》调用收银台
   - 参考《5.4 商户下单支付参数定义》构建支付参数

3. **步骤10、11 - 支付通知**：
   - 支付通知有两种推送方式，具体细节参考《7.1 建行生活支付通知接口》：
     - **方式1**：网银通知建行生活，再由建行生活转发给服务方（推荐）
     - **方式2**：网银直接通知服务方

4. **步骤13、16 - 订单状态更新**：
   - 由服务方调用订单更新接口（**A3341TP02**）向建行生活更新订单状态
   - 参考《3.2 A3341TP02 - 服务方订单更新》

5. **步骤14、15 - 主动查询**：
   - 服务方可以向外联平台主动查询订单交易流水，判断订单的支付状态
   - 也可以使用订单查询接口（**A3341TP03**）查询订单状态
   - 参考《3.3 A3341TP03 - 服务方订单查询》

**业务流程图：**

```
用户 → 服务方H5页面 → 调用订单推送接口(A3341TP01) → 建行生活
                    ↓
                调用收银台(支付参数)
                    ↓
            建行生活/建行App收银台
                    ↓
                 用户支付
                    ↓
        ┌───────────┴───────────┐
        ↓                       ↓
    支付成功页面         支付通知(方式1或方式2)
        ↓                       ↓
    回调服务方H5         服务方后台接收通知
        ↓                       ↓
    用户确认订单         更新订单状态(A3341TP02)
                                ↓
                        主动查询确认(A3341TP03)
```

---

### 5.4 商户下单支付参数定义（完整）

#### 参数说明

| 字段名 | 中文名 | 类型 | 是否非空 | 是否必送 | 备注 |
|--------|--------|------|----------|----------|------|
| **MERCHANTID** | 商户代码 | CHAR(15) | Y | F | 由建行统一分配 |
| **POSID** | 柜台代码 | CHAR(9) | Y | F | 由建行统一分配，9位柜台号 |
| **BRANCHID** | 分行代码 | CHAR(9) | Y | F | 由建行统一分配 |
| POSID19 | 商户19位终端号 | CHAR(19) | N | F | 由建行统一分配，使用微信支付时上送。仅作为参数传递，不参与MAC校验 |
| **PLATMCTID** | 外部平台商户号 | CHAR(19) | Y | F | 当使用外部商户号时，建行商户号、柜台号、分行号及终端号无需上送。当该字段有值时参与MAC校验，否则不参与MAC校验 |
| **ORDERID** | 支付流水号 | CHAR(30) | Y | T | 由商户提供，最长30位，支付时上送到支付中台，支付结果查询和退款使用 |
| **USER_ORDERID** | 用户订单号 | CHAR(30) | Y | T | 由商户提供，最长30位，用户订单列表订单信息，订单推送和更新时订单号，支付校验订单信息 |
| **PAYMENT** | 付款金额 | NUMBER(16,2) | Y | T | 由商户提供，最长30位 |
| **CURCODE** | 币种 | CHAR(2) | Y | T | 缺省为 01－人民币（只支持人民币支付） |
| **TXCODE** | 交易码 | CHAR(6) | Y | T | 由建行统一分配为 520100 |
| REMARK1 | 备注1 | CHAR(30) | N | T | 网银不处理，直接传到城综网，该字段只支持送数字和英文 |
| **REMARK2** | 备注2 | CHAR(30) | Y | T | 上送 YS 开头的服务方编号，与 PLATFORMID 保持一致 |
| **TYPE** | 接口类型 | CHAR(1) | Y | T | 默认送 1 - 防钓鱼接口 |
| **GATEWAY** | 网关类型 | CHAR(100) | Y | T | 默认送 0 |
| CLIENTIP | 客户端IP | CHAR(40) | N | T | 送空值即可 |
| REGINFO | 客户注册信息 | CHAR(256) | N | T | 客户在商户系统中注册的信息，中文需使用 escape 编码。送空值即可 |
| **PROINFO** | 商品信息 | CHAR(256) | N | T | 客户购买的商品信息，收银台会展示该信息，中文需使用 escape 编码。建议编码前长度不超过50位 |
| REFERER | 商户URL | CHAR(100) | N | T | 商户送空值即可 |
| INSTALLNUM | 分期期数 | CHAR(2) | N | F | 信用卡支付分期期数，一般为 3、6、12 等，必须为大于 1 的整数。仅当分期支付时上送该字段，无此字段上送时，则视为普通支付 |
| **THIRDAPPINFO** | 客户端标识 | CHAR(40) | Y | T | 通过建行相关App下单场景，订单中客户端标识固定设为 `comccbpay1234567890cloudmerchant` |
| TIMEOUT | 订单超时时间 | CHAR(14) | N | F | 格式：YYYYMMDDHHMMSS（如：20120214143005）银行系统时间 > TIMEOUT 时拒绝交易，若送空值则不判断超时。当该字段有值时参与MAC校验，否则不参与MAC校验 |
| USERID | 建行生活用户ID | CHAR(32) | N | F | 仅在中国建设银行App环境使用。当该字段有值时参与MAC校验，否则不参与MAC校验 |
| TOKEN | 建行生活用户TOKEN | CHAR(32) | N | F | 仅在中国建设银行App环境使用。当该字段有值时参与MAC校验，否则不参与MAC校验 |
| PAYSUCCESSURL | 支付成功页面URL | CHAR(128) | N | F | 仅在中国建设银行App环境使用，如需指定支付成功页面时提供，需对URL编码，生产环境必须为HTTPS。未提供则默认跳转到建行生活的支付成功页面。当该字段有值时参与MAC校验，否则不参与MAC校验 |
| PAYBITMAP | 支付位图 | CHAR(10) | N | F | 默认为空，特定场景使用 |
| ACCOUNTBITMAP | 支付账户位图 | CHAR(10) | N | F | 默认为空，特定场景使用 |
| POINTAVYID | 积分二级活动编号 | VARCHAR(6) | N | F | 默认为空，特定场景使用。龙支付积分二级活动上送 010051 |
| DCEPDEPACCNO | 数字人民币收款钱包编号 | VARCHAR(32) | N | F | 默认为空，特定场景使用。数字人民币商户绑定的收款钱包编号 |
| COUPONAVYID | 有价券活动编号 | VARCHAR(32) | N | F | 默认为空，特定场景使用 |
| ONLY_CREDIT_PAY_FLAG | 限制信用卡支付标志 | CHAR(1) | N | F | 默认为空，特定场景使用。当有价券活动编号不为空时生效，送Y限制仅信用卡能支付，送N或空不作限制 |
| FIXEDPOINTVAL | 固定抵扣积分值 | VARCHAR(16) | N | F | 默认为空，特定场景使用。上送该值时，若用户不满足积分使用条件将拒绝支付 |
| MINPOINTLIMIT | 最小使用积分抵扣限制 | VARCHAR(16) | N | F | 默认为空，特定场景使用。上送整数值时，视为最小积分抵扣数额；上送小于1的小数时，视为最小积分抵扣比例。若用户不满足积分使用条件将拒绝支付 |
| IDENTITYCODE | 身份证后6位 | VARCHAR(256) | N | F | 默认为空，特定场景使用。仅中石化服务方可用。身份证号后6位加密串，用于身份识别。加密说明：用服务方公钥对身份证后6位进行RSA加密，再进行base64，再进行encodeURIComponent一次 |
| NOTIFY_URL | 支付异步通知地址 | VARCHAR(512) | N | F | 默认为空，特定场景使用。仅中石化服务方可用。支付结果异步通知地址的encodeURIComponent编码值，多个通知地址时，分隔符用英文半角符号 , 分隔 |
| DCEP_MCT_TYPE | 数币商户类型 | CHAR(1) | N | F | 默认为空，特定场景使用。0\空-不识别为数币商户;1-融合商户;2-非融合商户 |
| DCEP_MERCHANTID | 数字人民币商户号 | CHAR(15) | N | F | 默认为空，特定场景使用。当 DCEP_MCT_TYPE 为 2 时上送值 |
| DCEP_POSID | 数字人民币柜台号 | CHAR(9) | N | F | 默认为空，特定场景使用。当 DCEP_MCT_TYPE 为 2 时上送值 |
| DCEP_BRANCHID | 数字人民币分行号 | CHAR(9) | N | F | 默认为空，特定场景使用。当 DCEP_MCT_TYPE 为 2 时上送值 |
| SUB_MCT_ID | 服务方二级商户编号 | VARCHAR(20) | N | F | 默认为空，涉及银联反欺诈时使用。若支付发起方为平台类服务方，需上送第三方平台下实际发起支付的二级商户所对应的商户编号 |
| SUB_MCT_NAME | 服务方二级商户名称 | VARCHAR(40) | N | F | 默认为空，涉及银联反欺诈时使用。若支付发起方为平台类服务方，需上送第三方平台下实际发起支付的二级商户所对应的商户名称 |
| SUB_MCT_MCC | 服务方二级商户类别 | CHAR(4) | N | F | 默认为空，涉及银联反欺诈时使用。若支付发起方为平台类服务方，需上送第三方平台下实际发起支付的二级商户所对应的商户MCC码 |
| EXTENDPARAMS | 扩展域 | VARCHAR(256) | N | F | 默认为空，特定场景使用。上送约定JSON格式字符串 |
| **PLATFORMPUB** | 服务方公钥 | VARCHAR(256) | Y | F | 仅作为源串参加 MD5 摘要，不作为参数传递 |
| **MAC** | MD5加密串 | CHAR(32) | Y | T | 采用标准 MD5 算法，对以上字段进行 MAC 加密（32位小写），由商户实现 |
| **PLATFORMID** | 服务方编号 | CHAR(16) | Y | T | 以 YS 开头的16位编号。仅作为参数传递，不参与MAC校验 |
| ENCPUB | 商户公钥密文 | VARCHAR(512) | Y | F | 使用服务方公钥对商户公钥后30位进行 RSA 加密并 base64 后的密文。若商户已经上架建行生活并同步公钥，或是使用外部商户号时，可以不再上送商户公钥。仅作为参数传递，不参与MAC校验 |
| SCNID | 场景编号 | VARCHAR(32) | N | F | 默认为空，埋点使用。特色场景的唯一标识。仅作为参数传递，不参与MAC校验 |
| SCN_PLTFRM_ID | 场景平台编号 | VARCHAR(32) | N | F | 默认为空，埋点使用。场景平台唯一标识。仅作为参数传递，不参与MAC校验 |

#### 字段说明

**是否非空**：
- `Y` - 上送该字段时，值不可为空
- `N` - 值可以为空

**是否必送**：
- `T` - 该字段必须上送，无论是否有值
- `F` - 字段可以不送

**重点字段**（已用粗体标注）：
1. **商户标识**：MERCHANTID、POSID、BRANCHID、PLATMCTID
2. **订单标识**：ORDERID、USER_ORDERID
3. **金额信息**：PAYMENT、CURCODE
4. **交易信息**：TXCODE、TYPE、GATEWAY
5. **服务方信息**：REMARK2、PLATFORMID、PLATFORMPUB
6. **客户端标识**：THIRDAPPINFO
7. **商品信息**：PROINFO
8. **签名信息**：MAC

#### MD5 签名计算详解

**签名规则：**

采用标准 MD5 摘要算法对字符串数据签名（32位小写），得到 MAC。

> **注意**：和交易通讯报文的 mac 区分，签名时不需要额外拼接 privateKey

**参与签名的字段：**

1. **必须参与签名的字段**（按顺序）：
   - MERCHANTID（或 PLATMCTID）
   - POSID
   - BRANCHID
   - ORDERID
   - USER_ORDERID
   - PAYMENT
   - CURCODE
   - TXCODE
   - REMARK1
   - REMARK2
   - TYPE
   - GATEWAY
   - CLIENTIP
   - REGINFO
   - PROINFO
   - REFERER
   - THIRDAPPINFO

2. **有值时参与签名的字段**（橙色字段）：
   - PLATMCTID（使用外部平台商户号时）
   - TIMEOUT
   - USERID
   - TOKEN
   - PAYSUCCESSURL
   - DCEP_MCT_TYPE
   - 其他特定场景字段

3. **最后拼接**：
   - PLATFORMPUB（服务方公钥）

**签名计算示例：**

```
参与签名的字符串（按顺序拼接，格式：字段名=值&字段名=值）：

MERCHANTID=105910100194086&POSID=313368474&BRANCHID=441000000&ORDERID=202209020000000061&USER_ORDERID=202209020000000061&PAYMENT=22.39&CURCODE=01&TXCODE=520100&REMARK1=&REMARK2=YS44000098000600&TYPE=1&GATEWAY=0&CLIENTIP=&REGINFO=&PROINFO=&REFERER=&THIRDAPPINFO=comccbpay1234567890cloudmerchant&TIMEOUT=20220902103420&DCEP_MCT_TYPE=1&PLATFORMPUB=MIGfMA0GCSqGSIb......

然后对整个字符串进行 MD5 加密（32位小写）：
MAC=f07ef63236e3bbbc1dc221b06e631f3d
```

#### 中文信息编码

**REGINFO（客户注册信息）** 和 **PROINFO（商品信息）** 中的中文需要使用 JavaScript 的 `escape()` 方法进行编码，数字字母信息不需编码。

**编码示例：**

```javascript
escape("小飞侠") = "%u5C0F%u98DE%u4FA0"
escape("A1级牛排") = "A1%u7EA7%u725B%u6392"
```

#### 商户公钥密文（ENCPUB）

**ENCPUB** 是各服务方使用自己的**服务方公钥**对**商户公钥后30位**进行 RSA 加密，再进行 base64 后，生成的密文串。

**生成步骤：**

1. 取商户公钥的后30位字符
2. 使用服务方公钥进行 RSA 加密
3. 对加密结果进行 base64 编码
4. 得到 ENCPUB 密文串

> **注意**：若商户已经上架建行生活并同步公钥，或是关联了外部平台商户号，可以不再上送商户公钥。
>
> 公钥加密方法见《6.2 报文加密及签名》章节。

#### 外部平台商户号说明（PLATMCTID）

外部平台商户号用于服务方已在建行生活完成商户关联，且收款商户已上架建行生活的场景。

**使用规则：**

- **使用外部平台商户号时**：
  - 必须上送 PLATMCTID
  - 无需上送 MERCHANTID、POSID、BRANCHID
  - PLATMCTID 参与 MAC 校验

- **不使用外部平台商户号时**：
  - 必须上送 MERCHANTID、POSID、BRANCHID
  - 无需上送 PLATMCTID

#### 扩展域说明（EXTENDPARAMS）

该字段仅提供给特定服务方场景使用，内容为双方约定值，格式为 **JSON 字符串**，上送时需要 **encodeURI 编码**。

**示例 - 善融积分：**

```json
{
    "scene": "pointPay",        // 场景
    "pointAmount": "1.50",      // 积分金额
    "pointNum": "1050"          // 积分数量
}
```

**使用步骤：**

1. 构建 JSON 字符串
2. 使用 encodeURI 进行编码
3. 将编码后的字符串作为 EXTENDPARAMS 的值

> 更多扩展域格式请参考原文档的"扩展域列表"章节

#### PAYBITMAP 和 ACCOUNTBITMAP 说明

两个字段分别为定长 **10位数字的位图**，位图为 `1` 表示可用，为 `0` 表示不可用。

**PAYBITMAP（支付方式位图）：**

| 位数 | 支付方式 | 说明 |
|------|----------|------|
| 第1位 | 生活钱包支付 | 1=可用，0=不可用 |
| 第2位 | 龙支付 | 1=可用，0=不可用 |
| 第3位 | 微信支付 | 1=可用，0=不可用 |
| 第4位 | 数币支付 | 1=可用，0=不可用 |
| 第5位 | 信用付 | 1=可用，0=不可用 |
| 第6位 | 快贷支付 | 1=可用，0=不可用 |
| 第7-10位 | 保留 | 预留位 |

**ACCOUNTBITMAP（支付账户位图，仅对龙支付及生活钱包下的卡账户生效）：**

| 位数 | 账户类型 | 说明 |
|------|----------|------|
| 第1位 | 建行借记卡 | 1=可用，0=不可用 |
| 第2位 | 建行贷记卡 | 1=可用，0=不可用 |
| 第3位 | 他行借记卡 | 1=可用，0=不可用 |
| 第4位 | 他行贷记卡 | 1=可用，0=不可用 |
| 第5位 | 建行钱包 | 1=可用，0=不可用 |
| 第6-10位 | 保留 | 预留位 |

**使用说明：**

- 两个字段可单独使用
- 未上送时默认全部支付方式都支持，即全为 `1`（1111111111）
- 该位图字段在判断支付方式是否可用时**优先级最低**
- 仅当商户已支持某一种支付方式时，服务方可对其决定是否使用
- 例如商户不支持微信支付，即使位图上送 `1` 也不会生效

**示例：**

```
PAYBITMAP=1110000000    // 仅支持生活钱包、龙支付、微信支付
ACCOUNTBITMAP=1100000000  // 仅支持建行借记卡和建行贷记卡
```

#### ORDERID 和 USER_ORDERID 的区别

| 字段 | 用途 | 说明 |
|------|------|------|
| **ORDERID** | 商户支付流水号 | 用于建行收单支付流程，包括在支付、查询支付结果及退款交易中使用 |
| **USER_ORDERID** | 用户订单号 | 用于同步用户在建行生活中的订单状态，包括在订单推送及状态更新时使用 |

**使用场景：**

- **ORDERID**：调用收银台时上送的支付流水号（对应收银台 ORDERID 字段）
- **USER_ORDERID**：建行生活订单列表展示的订单号（对应收银台 USER_ORDERID 字段，支付时会校验订单信息）

#### 最终参数串示例

完整的支付参数串由以下部分组成：

```
参与验签字符串 + MAC + PLATFORMID + ENCPUB

示例：
MERCHANTID=105910100194086&POSID=313368474&BRANCHID=441000000&ORDERID=202209020000000061&USER_ORDERID=202209020000000061&PAYMENT=22.39&CURCODE=01&TXCODE=520100&REMARK1=&REMARK2=YS44000098000600&TYPE=1&GATEWAY=0&CLIENTIP=&REGINFO=&PROINFO=&REFERER=&THIRDAPPINFO=comccbpay1234567890cloudmerchant&TIMEOUT=20220902103420&DCEP_MCT_TYPE=1&MAC=f07ef63236e3bbbc1dc221b06e631f3d&PLATFORMID=YS44000098000600&ENCPUB=YzNxRGtKSkFYZURRczYvNDN6WVZkYk......
```

> **注意**：
> - MAC 不参与 MAC 校验，但需要包含在最终参数串中
> - PLATFORMID 仅作为参数传递，不参与 MAC 校验
> - ENCPUB 仅作为参数传递，不参与 MAC 校验

---

## 6. 报文规范与加密

### 6.1 报文结构

#### 6.1.1 请求报文格式

请求报文由两部分组成：**交易请求报文头（CLD_HEADER）** 和 **交易请求报文体（CLD_BODY）**。

**报文头字段（CLD_HEADER）：**

| 字段标识 | 字段中文名 | 字段说明 | 数据属性 | 是否必填 | 备注 |
|----------|------------|----------|----------|----------|------|
| CLD_TX_CHNL | 报文来源渠道 | 消息来源渠道 | CHAR(20) | Y | 以 YS 开头的服务方编号 |
| CLD_TX_TIME | 报文交易时间 | 交易时间 | CHAR(14) | Y | 上送交易时间，格式: yyyyMMddHHmmss |
| CLD_TX_CODE | 交易服务ID | 服务ID | CHAR(64) | Y | 调用的交易名称 |
| CLD_TX_SEQ | 交易流水标识 | 流水号 | CHAR(32) | Y | 用于标识唯一性 |

**请求报文示例：**

```json
{
    "CLD_HEADER": {
        "CLD_TX_CHNL": "YSTEST",
        "CLD_TX_TIME": "20241231090000",
        "CLD_TX_CODE": "A3341TP01",
        "CLD_TX_SEQ": "1010114131620897033814262"
    },
    "CLD_BODY": {
        // 具体业务参数
    }
}
```

#### 6.1.2 响应报文格式

响应报文由两部分组成：**交易响应报文头（CLD_HEADER）** 和 **交易响应报文体（CLD_BODY）**。

**报文头字段（CLD_HEADER）：**

| 字段标识 | 字段中文名 | 字段说明 | 数据属性 | 是否必填 | 备注 |
|----------|------------|----------|----------|----------|------|
| CLD_TX_CHNL | 报文来源渠道 | 消息来源渠道 | CHAR(20) | Y | 以 YS 开头的服务方编号 |
| CLD_TX_TIME | 报文交易时间 | 交易时间 | CHAR(14) | Y | 格式: yyyyMMddHHmmss |
| CLD_TX_CODE | 交易服务ID | 服务ID | CHAR(64) | Y | 调用的交易名称 |
| CLD_TX_SEQ | 交易流水标识 | 流水号 | CHAR(32) | Y | 用于标识唯一性 |
| CLD_CODE | 交易响应码 | 响应码 | CHAR(32) | Y | 详见响应字典 |
| CLD_DESC | 交易响应内容 | 响应描述 | CHAR(32) | Y | 响应描述信息 |

**响应报文示例：**

```json
{
    "CLD_HEADER": {
        "CLD_TX_CHNL": "YSTEST",
        "CLD_TX_TIME": "20151231090000",
        "CLD_TX_CODE": "A3341TP01",
        "CLD_TX_SEQ": "1010114131620897033914221",
        "CLD_TX_RESP": {
            "CLD_CODE": "0000",
            "CLD_DESC": "成功"
        }
    },
    "CLD_BODY": {
        // 具体业务返回数据
    }
}
```

#### 6.1.3 报文编码说明

- 报文使用 **UTF-8** 编码
- 非二进制类型报元单个报元长度建议在 9999 位以内
- 整体报文大小建议在 20K 以内
- 登录类交易可以在 2M 以内（考虑到账户数量较多的情况）

---

### 6.2 报文加密及签名

#### 6.2.1 加密流程说明

服务方主动调用建行生活的接口时，需传递的是 **服务方编号**、**RSA密文** 及 **签名** 三个数据。

**加密后报文格式：**

```json
{
    "svcid": "服务方ID，以YS开头",
    "cnt": "密文xxxx",
    "mac": "签名yyyy"
}
```

**错误响应格式：**

```json
{
    "code": "错误码xxxx",
    "msg": "错误描述yyyy"
}
```

#### 6.2.2 加密签名方法（Java 示例）

**加密及获取签名：**

```java
// 公钥
String publicKey = "";
// 私钥
String privateKey = "";

// 源报文(未加密)
String msg = "";

// 1. 公钥加密得到密文并使用 base64 处理
String enc_msg = RSAUtil.encrypt(msg, publicKey);
Encoder encoder = Base64.getEncoder();
enc_msg = encoder.encodeToString(enc_msg.getBytes("UTF-8"));
enc_msg = enc_msg.replaceAll("\r\n", "").replaceAll("\r", "").replaceAll("\n", "");

// 2. 根据源报文+私钥获得 MD5 签名
String mac_info = MD5Util.getMD5(msg + privateKey);
```

**解密及验签：**

```java
// 1. base64 逆处理并用私钥解密
Decoder decoder = Base64.getMimeDecoder();
enc_msg = new String(decoder.decode(enc_msg), "UTF-8");
String dec_msg = RSAUtil.decrypt(enc_msg, privateKey);

// 2. 验签
String dec_mac = MD5Util.getMD5(dec_msg + privateKey);
if (mac_info.equals(dec_mac)) {
    System.out.println("验签通过");
} else {
    System.out.println("验签失败");
}
```

> **提示**：如果使用的 JDK 版本高于 1.8，请将 base64 方法由 `sun.misc.BASE64Encoder` 替换为 `java.util.Base64`

#### 6.2.3 加密报文完整示例

**原始报文：**

```json
{
    "CLD_HEADER": {
        "CLD_TX_CHNL": "YSTEST",
        "CLD_TX_TIME": "20191112145911",
        "CLD_TX_CODE": "A3341TP01",
        "CLD_TX_SEQ": ""
    },
    "CLD_BODY": {
        "USER_ID": "user123",
        "ORDER_ID": "order123",
        "ORDER_DT": "20191112145811",
        "TOTAL_AMT": "100.00",
        "PAY_AMT": "90.00",
        "DISCOUNT_AMT": "10.00",
        "ORDER_STATUS": "1",
        "REFUND_STATUS": "0",
        "MCT_NM": "XXX商户"
    }
}
```

**加密后报文：**

```json
{
    "cnt": "UWl3VVVIT0IzSHp6VUtpNFVmb25VcWJjMnBKdU9IclJUZ3lISGJLR3Myd21saWQvMTVvenNMNk5xWmFwUzl1clh5K2VkVmJuU1BYMg0KTzUwamNkZWRmdjc5NHdDRmJSdjF4WDl4bzAwejMwU2k2NXJ6cTVaVVU4dUt2ZmNPeVJ1cDJkTC9SOUgvODVUblNLbEVXUnErSGo3dw0KMzB2YjFaeU1acU5iRVZnb25VSTUrcmlPV2wweWUwb2xQTVFoei9CVWhDcU9qOExqR21hTDBCdGpVbVdiTyttU3Vpa0s5Y25md3g0SQ0KV0xUSk1BWjl3OHdkZ0FqamI5bXhJbFJUM3JrU3VId1RMdGF0VkdJcGovVDAvdk5nQzNUcWgvODJOQnZvYXdoYnl0Z3AwRW9FNWp5bw0KdVhmYVZDZE9IeGp4ZkpyclFFSCt5THFoZXl2MEx2OGJ1b0x0N0pYMi9zM0pJS0J1bFdSZWJHRTMrcmpEMm9sUVJiYklONkdpeDlodQ0KUEprWkFkK0UrcTV1ZFR4OXpFRlJyWVBHVURzL0RLK0JFSk5iYWZGRnllZTBrRzh2YVlmU1NxeFBWcVBrblRzZ2oxdXFqME0xTGFCNQ0KZ1drVU9vVnl4bUtXUEpYd3JqYXlkSUxVeEZ2dkwzZEpHYmV6cnUwK3d1V3A2QXBQVnRkOElaSm4NCg==",
    "mac": "1659E42FC9D2A2186228C4607A566D78",
    "svcid": "YSTEST"
}
```

---

## 7. 回调通知接口

### 7.1 建行生活支付通知接口

#### 7.1.1 背景描述

如服务方生活场景涉及支付环节，必须按本章节要求完成支付回调通知对接。

⚠️ **重要提示**：
- 支付结果推送接口属于建行生活主动推送给服务方，所以不会附带服务方编号
- 服务方接收支付通知的系统地址，需要配置在建行生活运营后台，请联系运维进行配置
- 因网络问题存在支付通知丢失的可能性，请服务方考虑通过主动查询支付流水的方式作为兜底（参考《3.3 A3341TP03 - 服务方订单查询》）

#### 7.1.2 接口推送报文示例

```json
{
    "ACC_TYPE": "WX",
    "BRANCHID": "310000000",
    "CCB_DISCOUNT_AMT": "",
    "CCB_DISCOUNT_AMT_DESC": "",
    "CLIENTIP": "11.123.44.55",
    "CURCODE": "01",
    "MRCH_ID": "",
    "NT_TYPE": "YS",
    "ORDERID": "210520133844test3yhv",
    "PAYMENT": "0.01",
    "PAY_TYPE": "01",
    "POSID": "123442025",
    "REFERER": "",
    "REMARK1": "",
    "REMARK2": "YS1234009000111**WXZF",
    "SIGN": "1a4aca34f02c0efab014ff823153a2a07a35a8a8410591a992d4aa9cd7fa1f961b952236a45b4fe37867ad4a7214ecbeae21957dee9c19d3d2f5dcf09c8faca81ceb68119c8dcd53bd1e70c23f60fc03e7cd96b8c0082a1243d688c13aac0bcd9e177c559e40e782e3856ada32de8d8ce0054e35fca2022b8f91b2a1ca2c5e10",
    "SUCCESS": "Y",
    "TYPE": "1"
}
```

#### 7.1.3 字段说明

##### REMARK2 字段说明

发起支付时（调用商户下单支付接口），把服务方编号通过 `REMARK2` 字段送到支付渠道，让支付渠道再推送结果给建行生活时，建行生活根据该字段来判断订单归属哪个服务方，然后指定推送订单结果给对应的服务方（需要在后台维护服务方系统地址）。

##### SIGN 字段说明

使用商户私钥对报文进行 RSA 签名，服务方需要使用建行公钥验签。

##### CCB_DISCOUNT_AMT 和 CCB_DISCOUNT_AMT_DESC 字段说明

- 由建行生活推送给服务方的支付通知会额外携带该笔订单所使用的优惠金额
- 但是由网银直接推送的支付通知，只含原订单金额，不包含优惠金额，需要服务方自行向外联平台查询

---

### 7.2 建行生活退款操作通知接口

#### 7.2.1 背景描述

如服务方场景需要接收退款操作消息通知，必须按本章节要求完成退款回调通知对接。

⚠️ **重要提示**：
- **不能用于退款结果判断**：退款操作消息推送仅推送商户号、订单号等少量用于查询使用的信息
- 若需获知退款状态、金额、优惠信息和支付方式等信息，参考《3.3 A3341TP03 - 服务方订单查询》
- 如服务方场景仅通过 A3341TP04 服务方退款交易完成退款，已实现退款流程的闭环，可略过本章节
- 订单退款操作消息推送属于建行生活主动推送给服务方，不会附带服务方编号
- 服务方接收退款操作消息通知的回调地址，需要配置在建行生活运营后台，请联系运维进行配置

#### 7.2.2 接口推送报文示例

```json
{
    "MRCH_ID": "1050000000000000000",
    "NT_TYPE": "YS",
    "ORDERID": "210520133844test3yhv",
    "REFUND_DTM": "20250601120000",
    "SIGN": "317b7dd349c1fbcabc26a20ba117a778da5a685c588be5e7378682651062a25b0885e36ee237c19a143f7271c9529a0e9bf198c8735709dc74233d96e1a276cec9d4835422bee597100b0a47d11b44dbba74bdf9cbde0587f138141ce79a3536733d5f6b53ed119c13708dca52ee8d3fcf7e67dcdb20053889adff1989a8c859"
}
```

#### 7.2.3 字段说明

| 字段名 | 中文名 | 类型 | 说明 |
|--------|--------|------|------|
| MRCH_ID | 商户号 | String | 建行商户编号 |
| NT_TYPE | 通知类型 | String | 固定值 "YS" |
| ORDERID | 订单号 | String | 支付流水号 |
| REFUND_DTM | 退款时间 | String | 格式: yyyyMMddHHmmss |
| SIGN | 签名 | String | RSA 签名，需使用建行公钥验签 |

---

**文档结束**