mirror of
https://gitee.com/liuxioabin/fengketrade.git
synced 2026-04-17 12:57:32 +08:00
357 lines
9.5 KiB
Markdown
357 lines
9.5 KiB
Markdown
# 建行相关App服务方接入文档分析
|
||
|
||
## 一、文档概述
|
||
|
||
这份文档（v2.20_20250725）是建行生活App和中国建设银行App的服务方接入指南，涵盖了：
|
||
- 环境识别方法
|
||
- 收银台调用方式
|
||
- 支付参数规范
|
||
- 接口地址和协议
|
||
|
||
## 二、关键接口地址（确认）
|
||
|
||
### 2.1 后台接口地址
|
||
|
||
| 环境 | 地址 | 用途 |
|
||
|------|------|------|
|
||
| **测试环境** | `http://124.127.94.60:18088/uat_new/tp_service/txCtrl/server?txcode=xxx` | 后台交易接口 |
|
||
| **生产环境** | `https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=xxx` | 后台交易接口 |
|
||
|
||
### 2.2 前端收银台地址
|
||
|
||
| 环境 | 地址 | 用途 |
|
||
|------|------|------|
|
||
| **测试环境** | `http://124.127.94.60:18088/uat_new/clp_service/txCtrl` | 收银台处理URL |
|
||
| **生产环境** | `https://yunbusiness.ccb.com/clp_service/txCtrl` | 收银台处理URL |
|
||
|
||
**调用格式**：
|
||
```
|
||
url?txcode=A3341OM01&svcid=服务方编号&cnt=加密内容&mac=签名
|
||
```
|
||
|
||
## 三、H5商城在建行App中的运行机制
|
||
|
||
### 3.1 环境识别
|
||
|
||
#### 建行生活App识别：
|
||
```javascript
|
||
// 方法1：检查URL参数
|
||
if (location.search.includes('platform=ccblife')) {
|
||
console.log('在建行生活App中');
|
||
}
|
||
|
||
// 方法2：检查UA（更准确）
|
||
window.CCBBridge.requestNative(JSON.stringify({
|
||
action: "getUA",
|
||
params: {}
|
||
}), "getUACallBack");
|
||
```
|
||
|
||
#### 中国建设银行App识别：
|
||
```javascript
|
||
// 检查URL参数中是否有platform=ccb
|
||
if (location.search.includes('platform=ccb')) {
|
||
console.log('在中国建设银行App中');
|
||
}
|
||
```
|
||
|
||
### 3.2 跳转URL格式
|
||
|
||
建行App跳转到H5商城时，URL格式为：
|
||
```
|
||
https://your-h5-mall.com?platform=ccblife&channel=mbs&ccbParamSJ=xxx&CITYID=330100&USERCITYID=440100
|
||
```
|
||
|
||
**参数说明**：
|
||
- `platform`：平台标识（ccblife或ccb）
|
||
- `ccbParamSJ`：加密参数串（包含用户信息）
|
||
- `CITYID`：用户所在城市
|
||
- `USERCITYID`：用户选择城市
|
||
|
||
## 四、支付接入详解
|
||
|
||
### 4.1 调起收银台方法
|
||
|
||
#### 在建行生活App中（iOS）：
|
||
```javascript
|
||
function MBS_DIRECT_PAY(payInfo) {
|
||
// payInfo为支付参数串
|
||
window.location = "mbspay://direct?" + payInfo;
|
||
}
|
||
```
|
||
|
||
#### 在建行生活App中（Android）：
|
||
```javascript
|
||
function MBS_DIRECT_PAY(payInfo) {
|
||
window.mbspay.directpay(payInfo);
|
||
}
|
||
```
|
||
|
||
#### 在中国建设银行App中：
|
||
需要先进行RSA加密，然后跳转到收银台URL：
|
||
```javascript
|
||
// 1. 组装支付参数
|
||
// 2. RSA加密
|
||
// 3. 跳转到收银台URL
|
||
window.location = 'https://yunbusiness.ccb.com/clp_service/txCtrl?txcode=A3341OM01&svcid=' + serviceId + '&cnt=' + encryptedData + '&mac=' + signature;
|
||
```
|
||
|
||
### 4.2 支付参数详解
|
||
|
||
#### 必需参数：
|
||
| 字段 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| MERCHANTID | 商户代码 | 由建行分配 |
|
||
| POSID | 柜台代码 | 由建行分配 |
|
||
| BRANCHID | 分行代码 | 由建行分配 |
|
||
| ORDERID | 订单号 | 商户订单号 |
|
||
| PAYMENT | 支付金额 | 单位：元 |
|
||
| CURCODE | 币种 | 01-人民币 |
|
||
| REMARK2 | 备注2 | **填写服务方编号（YS开头）** |
|
||
| MAC | MD5签名 | 见签名规则 |
|
||
| ENCPUB | 商户公钥密文 | RSA加密后的公钥 |
|
||
|
||
#### 重要字段说明：
|
||
- **REMARK2必须填写服务方编号**（如：YS44000098000600）
|
||
- **NOTIFY_URL**：支付通知回调地址（生产环境必须HTTPS）
|
||
- **PAYSUCCESSURL**：支付成功页面（可选）
|
||
|
||
### 4.3 支付成功回调设置
|
||
|
||
在调起收银台前，设置回调地址：
|
||
```javascript
|
||
var requestObj = {
|
||
action: 'setCache',
|
||
params: {
|
||
key: 'YS44000098000600', // 服务方编号，与REMARK2一致
|
||
value: 'https://your-domain.com/payment/success' // 回调URL
|
||
}
|
||
};
|
||
window.CCBBridge.requestNative(JSON.stringify(requestObj), 'callBackName');
|
||
```
|
||
|
||
### 4.4 签名生成规则
|
||
|
||
MD5签名生成步骤：
|
||
1. 按参数名ASCII排序拼接成字符串
|
||
2. 在字符串末尾加上服务方公钥
|
||
3. 使用MD5算法生成签名
|
||
|
||
```php
|
||
// PHP示例
|
||
$params = [
|
||
'MERCHANTID' => '105910100194086',
|
||
'POSID' => '313368474',
|
||
'ORDERID' => 'ORD123456',
|
||
// ... 其他参数
|
||
];
|
||
|
||
// 1. 排序并拼接
|
||
ksort($params);
|
||
$signStr = http_build_query($params);
|
||
|
||
// 2. 加上服务方公钥
|
||
$signStr .= '&PLATFORMPUB=' . $platformPublicKey;
|
||
|
||
// 3. 生成MD5
|
||
$mac = md5($signStr . $privateKey);
|
||
```
|
||
|
||
## 五、完整对接流程
|
||
|
||
### 5.1 业务流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant H5 as H5商城
|
||
participant Backend as 服务方后台
|
||
participant CCBApp as 建行App
|
||
participant CCBServer as 建行服务器
|
||
|
||
User->>CCBApp: 打开建行App
|
||
CCBApp->>H5: 跳转H5商城(带参数)
|
||
H5->>H5: 识别运行环境
|
||
User->>H5: 选购商品
|
||
H5->>Backend: 创建订单
|
||
Backend->>CCBServer: 推送订单(A3341TP01)
|
||
Backend-->>H5: 返回支付参数
|
||
H5->>CCBApp: 调起收银台
|
||
User->>CCBApp: 确认支付
|
||
CCBApp->>CCBServer: 支付请求
|
||
CCBServer-->>Backend: 支付通知
|
||
CCBServer-->>CCBApp: 支付结果
|
||
CCBApp-->>H5: 跳转回调页
|
||
```
|
||
|
||
### 5.2 接入步骤
|
||
|
||
1. **环境准备**
|
||
- 申请服务方编号（YS开头）
|
||
- 生成RSA密钥对
|
||
- 获取建行平台公钥
|
||
|
||
2. **H5页面适配**
|
||
- 识别运行环境
|
||
- 实现收银台调用方法
|
||
- 设置支付回调
|
||
|
||
3. **后端接口开发**
|
||
- 实现订单推送接口
|
||
- 实现支付参数生成
|
||
- 处理支付通知
|
||
|
||
4. **测试验证**
|
||
- 在UAT环境测试
|
||
- 验证支付流程
|
||
- 确认回调正确
|
||
|
||
## 六、UniApp实现方案
|
||
|
||
### 6.1 环境识别封装
|
||
```javascript
|
||
// utils/ccb-env.js
|
||
export default {
|
||
// 检查是否在建行环境
|
||
isInCCBApp() {
|
||
// #ifdef H5
|
||
const search = location.search.toLowerCase();
|
||
return search.includes('platform=ccblife') ||
|
||
search.includes('platform=ccb');
|
||
// #endif
|
||
|
||
// #ifndef H5
|
||
return false;
|
||
// #endif
|
||
},
|
||
|
||
// 获取平台类型
|
||
getPlatform() {
|
||
// #ifdef H5
|
||
if (location.search.includes('platform=ccblife')) {
|
||
return 'ccblife'; // 建行生活
|
||
}
|
||
if (location.search.includes('platform=ccb')) {
|
||
return 'ccb'; // 中国建设银行
|
||
}
|
||
// #endif
|
||
return null;
|
||
},
|
||
|
||
// 获取加密参数
|
||
getCCBParams() {
|
||
// #ifdef H5
|
||
const params = new URLSearchParams(location.search);
|
||
return {
|
||
ccbParamSJ: params.get('ccbParamSJ'),
|
||
cityId: params.get('CITYID'),
|
||
userCityId: params.get('USERCITYID')
|
||
};
|
||
// #endif
|
||
return {};
|
||
}
|
||
};
|
||
```
|
||
|
||
### 6.2 收银台调用封装
|
||
```javascript
|
||
// utils/ccb-payment.js
|
||
export default {
|
||
// 调起建行收银台
|
||
pay(paymentString) {
|
||
// #ifdef H5
|
||
const platform = this.getPlatform();
|
||
|
||
if (platform === 'ccblife') {
|
||
// 建行生活App
|
||
if (this.isIOS()) {
|
||
window.location = "mbspay://direct?" + paymentString;
|
||
} else {
|
||
// Android
|
||
if (window.mbspay && window.mbspay.directpay) {
|
||
window.mbspay.directpay(paymentString);
|
||
} else {
|
||
console.error('mbspay对象不存在');
|
||
}
|
||
}
|
||
} else if (platform === 'ccb') {
|
||
// 中国建设银行App - 需要跳转到收银台URL
|
||
// 这里需要后端返回加密后的URL
|
||
window.location = paymentString; // 这里应该是完整的收银台URL
|
||
}
|
||
// #endif
|
||
},
|
||
|
||
// 设置支付回调
|
||
setPayCallback(serviceId, callbackUrl) {
|
||
// #ifdef H5
|
||
if (window.CCBBridge && window.CCBBridge.requestNative) {
|
||
const requestObj = {
|
||
action: 'setCache',
|
||
params: {
|
||
key: serviceId,
|
||
value: callbackUrl
|
||
}
|
||
};
|
||
|
||
window.CCBBridge.requestNative(
|
||
JSON.stringify(requestObj),
|
||
'setPayCallbackResult'
|
||
);
|
||
}
|
||
// #endif
|
||
},
|
||
|
||
// 判断是否iOS
|
||
isIOS() {
|
||
return /iPhone|iPad|iPod/i.test(navigator.userAgent);
|
||
},
|
||
|
||
getPlatform() {
|
||
if (location.search.includes('platform=ccblife')) {
|
||
return 'ccblife';
|
||
}
|
||
if (location.search.includes('platform=ccb')) {
|
||
return 'ccb';
|
||
}
|
||
return null;
|
||
}
|
||
};
|
||
```
|
||
|
||
## 七、重要注意事项
|
||
|
||
### 7.1 关键配置
|
||
- **REMARK2必须填写服务方编号**
|
||
- **生产环境必须使用HTTPS**
|
||
- **支付通知接口需要验签**
|
||
|
||
### 7.2 常见问题
|
||
|
||
**Q: 如何区分建行生活和中国建设银行App？**
|
||
A: 通过URL参数platform判断，ccblife是建行生活，ccb是中国建设银行。
|
||
|
||
**Q: 支付参数需要加密吗？**
|
||
A: 在建行生活App中直接传递，在中国建设银行App中需要RSA加密。
|
||
|
||
**Q: 支付成功后如何跳转？**
|
||
A: 通过setCache方法设置回调URL，或使用PAYSUCCESSURL参数。
|
||
|
||
### 7.3 测试要点
|
||
1. 环境识别是否准确
|
||
2. 收银台能否正常调起
|
||
3. 支付回调是否正常
|
||
4. 订单状态同步是否及时
|
||
|
||
## 八、总结
|
||
|
||
这份文档确认了：
|
||
1. ✅ **接口地址明确**：包括后台接口和收银台URL
|
||
2. ✅ **支付流程清晰**：不同App环境有不同调用方式
|
||
3. ✅ **参数规范完整**：包括签名、加密等要求
|
||
4. ✅ **PHP/UniApp可以实现**：通过HTTP接口和JavaScript调用
|
||
|
||
关键点：
|
||
- 服务方编号（REMARK2）是核心参数
|
||
- 建行生活和中国建设银行App调用方式不同
|
||
- 所有接口都是标准HTTP/HTTPS，PHP完全可以对接 |