fengketrade/doc/建行App服务方接入文档分析.md

建行相关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识别：

// 方法1：检查URL参数
if (location.search.includes('platform=ccblife')) {
    console.log('在建行生活App中');
}

// 方法2：检查UA（更准确）
window.CCBBridge.requestNative(JSON.stringify({
    action: "getUA",
    params: {}
}), "getUACallBack");

中国建设银行App识别：

// 检查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）：

function MBS_DIRECT_PAY(payInfo) {
    // payInfo为支付参数串
    window.location = "mbspay://direct?" + payInfo;
}

在建行生活App中（Android）：

function MBS_DIRECT_PAY(payInfo) {
    window.mbspay.directpay(payInfo);
}

在中国建设银行App中：

需要先进行RSA加密，然后跳转到收银台URL：

// 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 支付成功回调设置

在调起收银台前，设置回调地址：

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示例
$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 业务流程

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 环境识别封装

// 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 收银台调用封装

// 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完全可以对接