更新记录

1.0.0（2026-06-27）

发布版本

平台兼容性

uni-app(4.56)

uni-app x(4.56)

jwh-ccb-pay

建行龙支付、建行聚合支付 UTS 插件。支持 App Android、App iOS、HarmonyOS，可按建行订单配置发起微信支付、支付宝支付等渠道。

支付行为说明

• provider: 'ccb' 建行龙支付：未安装建行手机银行 App 时，三端均按建行 SDK 推荐做法回退建行 H5 网页支付，不阻断支付流程。
• provider: 'aggregate' 建行聚合支付：由建行聚合收银台页面提供多渠道选择，各端入口保持原生 SDK 默认实现，未安装时的回退由收银台侧控制。
• 建行 SDK 不内置微信/支付宝客户端 SDK，插件已自行打包对应 SDK，无需额外引入微信开放平台 SDK。

配置总览

先准备这些值：

按支付方式配置

龙支付：provider: 'ccb'

聚合支付：provider: 'aggregate'

如果聚合页里要使用微信渠道，再按“微信支付”补齐微信开放平台配置。如果聚合页里要使用支付宝渠道，再按“支付宝支付”确认支付宝 scheme 配置。

微信支付：provider: 'wx'

支付宝支付：provider: 'alipay'

Android 必配

1. 修改建行回跳 action

文件位置：

uni_modules/jwh-ccb-pay/utssdk/app-android/AndroidManifest.xml

找到：

<activity
  android:name="com.ccb.ccbnetpay.activity.appresult.ResultActivity"
  android:configChanges="orientation|keyboardHidden|screenSize"
  android:exported="true"
  android:screenOrientation="portrait"
  tools:node="merge">
  <intent-filter>
    <action android:name="comccbpay你的商户号xxx" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

只改 <action> 这一行：

<action android:name="<ccbThirdAppInfo>" />

2. 检查微信回跳入口

文件位置：

uni_modules/jwh-ccb-pay/utssdk/app-android/AndroidManifest.xml

保留：

<activity-alias
  android:name="${applicationId}.wxapi.WXPayEntryActivity"
  android:exported="true"
  android:targetActivity="uts.sdk.modules.jwhCcbPay.WXPayEntryActivity"
  android:theme="@android:style/Theme.Translucent.NoTitleBar"
  tools:node="merge" />

3. 配置微信开放平台

使用 provider: 'wx' 时必须配置：

4. 不启用内置支付模块

文件位置：

manifest.json

不要配置 HBuilderX 内置支付：

{
  "app-plus": {
    "modules": {
      "Payment": {}
    },
    "distribute": {
      "sdkConfigs": {
        "payment": {}
      }
    }
  }
}

插件已声明：

iOS 必配

1. 配置 URL Schemes

文件位置：

manifest.json

配置位置：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "urltypes": "<ccbThirdAppInfo>,<wxAppId>"
      }
    }
  }
}

填写规则：

2. 配置微信开放平台

使用 provider: 'wx' 时必须配置：

3. 插件已声明

不要额外引入微信开放平台 SDK。

HarmonyOS 必配

1. 配置 querySchemes

文件位置按你的 HarmonyOS 工程结构，一般是：

entry/src/main/module.json5

按使用渠道配置：

示例：

{
  module: {
    querySchemes: [
      "ccbapp",
      "mbspay",
      "weixin",
      "wxopensdk",
      "https",
      "alipays"
    ]
  }
}

2. 微信支付初始化参数

使用 provider: 'wx' 时必须传：

initPayment({
  wxAppId: '<wxAppId>',
  want: harmonyWant
})

3. 插件已声明

服务端必配

服务端返回完整建行订单参数串 orderInfo：

MERCHANTID=...&POSID=...&BRANCHID=...&ORDERID=...&PAYMENT=...&TXCODE=...&THIRDAPPINFO=<ccbThirdAppInfo>&MAC=...

必须保持一致：

当前示例值替换清单：

快速接入

1. 引入插件

import {
  initPayment,
  pay,
  isAppInstalled,
  getSDKVersion
} from '@/uni_modules/jwh-ccb-pay'

2. 选择支付渠道

3. 复制支付代码

let wxReady = false

function ensureWxPaymentReady(provider, done) {
  if (provider !== 'wx') {
    done()
    return
  }

  if (wxReady) {
    done()
    return
  }

  initPayment({
    wxAppId: '<wxAppId>',
    wxUniversalLink: '<wxUniversalLink>',
    // HarmonyOS 微信支付时传入当前 want
    // want: harmonyWant,
    success: () => {
      wxReady = true
      done()
    },
    fail: (err) => {
      console.log('微信支付初始化失败', err)
    }
  })
}

function startPayment(provider, orderInfo) {
  if (!orderInfo) {
    console.log('orderInfo 不能为空')
    return
  }

  if (!isAppInstalled({ provider })) {
    console.log('未安装对应支付 App')
    return
  }

  ensureWxPaymentReady(provider, () => {
    pay({
      provider: provider,
      orderInfo: orderInfo,
      success: (res) => {
        console.log('支付成功', res)
      },
      fail: (err) => {
        if (err.errCode === 9010007) {
          console.log('用户取消支付', err)
          return
        }
        console.log('支付失败', err)
      },
      complete: (res) => {
        console.log('支付结束', res)
      }
    })
  })
}

4. 发起支付

startPayment('ccb', orderInfo)
startPayment('aggregate', orderInfo)
startPayment('wx', orderInfo)
startPayment('alipay', orderInfo)

直接调用：

pay({ provider: 'ccb', orderInfo })
pay({ provider: 'aggregate', orderInfo })
pay({ provider: 'wx', orderInfo })
pay({ provider: 'alipay', orderInfo })

API 参数

initPayment

微信支付初始化。

initPayment({
  wxAppId: '<wxAppId>',
  wxUniversalLink: '<wxUniversalLink>',
  want: harmonyWant,
  success: (res) => {},
  fail: (err) => {},
  complete: (res) => {}
})

pay

发起支付。

pay({
  provider: 'ccb',
  orderInfo: orderInfo,
  success: (res) => {},
  fail: (err) => {},
  complete: (res) => {}
})

isAppInstalled

检查支付 App。

const installed = isAppInstalled({ provider: 'wx' })

getSDKVersion

查看 SDK 版本。

console.log(getSDKVersion())

回调数据

成功回调：

{
  provider: 'ccb',
  status: 'success',
  errCode: 0,
  errMsg: 'pay:ok',
  raw: {}
}

失败回调：

{
  errCode: 9010006,
  errMsg: '支付失败：...',
  provider: 'ccb',
  raw: {}
}

常见返回

err.raw 保留 SDK 原始错误；err.errMsg 可能包含“原始错误”。

测试说明

当前插件已完成 Android、iOS 端建行龙支付流程测试。HarmonyOS 端建行龙支付，以及聚合支付、微信支付、支付宝支付依赖商户号开通状态、建行后台订单参数、支付平台配置、真实设备 App 安装状态和回跳配置，请接入方在自己的测试/生产商户环境中完成完整联调。

建议正式上线前至少验证：

• 正常支付成功后，客户端回调和服务端通知/查单结果一致。
• 用户取消支付时，业务侧不会误判为支付失败重试。
• 未安装目标支付 App、网络异常、订单重复、签名错误等异常场景能被正确处理。
• Android、iOS、HarmonyOS 使用到的渠道都在真机上完成回跳测试。

支付方式选择说明

• provider: 'ccb' 是建行龙支付，支持建行 App 支付和建行 H5 网页支付兜底。未安装建行手机银行 App 时，会按建行 SDK 能力回退到建行 H5 支付页面。
• provider: 'aggregate' 是建行聚合支付，会进入建行聚合收银台，由收银台展示商户已开通的支付渠道。用户在聚合页里选择微信或支付宝时，属于聚合收银台内的渠道选择，不等同于单独调用 provider: 'wx' 或 provider: 'alipay'。
• provider: 'wx' 是单独的微信 App 支付，需要安装微信并完成对应平台配置；插件不提供微信 H5 兜底。
• provider: 'alipay' 是单独的支付宝 App 支付，需要安装支付宝；插件不提供支付宝 H5 兜底。

如果业务希望“未安装支付 App 也能继续付款”，优先使用建行龙支付或建行聚合支付，并确保服务端返回的 orderInfo 与对应支付方式匹配。

购买前说明

请先体验插件并确认功能、支付流程、回调结果与自身业务逻辑相匹配后再进行购买。不同商户的建行后台配置、订单参数、支付渠道开通情况可能存在差异，建议在购买前完成关键流程验证。

如需根据自身业务场景调整支付逻辑、错误处理、回调封装或页面交互，可购买源码版本后自行二次开发。