From 461083cb7935d95788480fd5aa005f1794549fc8 Mon Sep 17 00:00:00 2001 From: Billy <641833868@qq.com> Date: Tue, 21 Oct 2025 13:42:55 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=8E=A5=E5=8F=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/建行生活API接口文档.md | 996 ++++++++++++++++++++++++++++- 1 file changed, 993 insertions(+), 3 deletions(-) diff --git a/doc/建行生活API接口文档.md b/doc/建行生活API接口文档.md index 628edc3..ed3a366 100644 --- a/doc/建行生活API接口文档.md +++ b/doc/建行生活API接口文档.md @@ -1,8 +1,11 @@ # 建行生活API接口文档 -> 文档版本: v1.1.6 -> 生成时间: 2025-01-21 -> 来源: 建行生活输入通讯报文v1.1.6【最新】.xlsx +> 文档版本: v2.0.0 +> 更新时间: 2025-10-21 +> 来源: +> - 建行生活输入通讯报文v1.1.6【最新】.xlsx +> - 建行生活原生与h5交互规范接口1.3（新）.html +> - 建行相关App服务方接入文档v2.20_20250725.html --- @@ -20,6 +23,23 @@ - [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-建行生活退款操作通知接口) --- @@ -34,6 +54,7 @@ | 2024-02-23 | 订单更新新增PLATFORM_POINT、PAY_MODE、GOODS_NM字段 | 已上线 | | 2024-02-26 | 增加权益信息查询接口 | 已上线 | | 2025-06-09 | 增加SKU_LIST字段 | 待上线 | +| 2025-10-21 | **整合多个文档**：新增 H5 与原生交互接口（JS Bridge）、服务方接入规范、报文加密与签名、回调通知接口等章节 | 文档整合 | --- @@ -565,4 +586,973 @@ P6:{FL3:有价折扣券,AM1:30.00,AM2:30.00},P3:{FL2:02,FL3:满减活动,AM1:30. --- +## 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 | 否 | 否 | 定位模式：
`0` 缓存优先，先返回上一次定位缓存再异步更新缓存
`1` 即时定位，loading等待即时定位后返回，并更新缓存（默认）
`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 | 错误码：
`1014` 用户未授权
`1016` 手机GPS开关未开启
`1017` 地图sdk返回失败
`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=®INFO=&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=®INFO=&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 签名，需使用建行公钥验签 | + +--- + **文档结束**