更新记录

1.0.1（2026-07-10）

• 按建行三端官方返回字段修正成功、失败、取消和待确认状态判断
• 修正 iOS 微信 Universal Link 参数和 HarmonyOS Want 回跳处理
• 增加并发支付保护，HarmonyOS 聚合支付改为明确返回不支持
• 更新示例、接入文档和插件权限声明

平台兼容性

uni-app(4.61)

uni-app x(4.61)

jwh-ccb-pay

建行龙支付、建行聚合支付 UTS 插件。Android、iOS 支持龙支付与聚合收银台；HarmonyOS 按建行 2.2 SDK 文档支持龙支付、微信和支付宝，暂不提供聚合收银台入口。

支付行为说明

• provider: 'ccb' 建行龙支付：未安装建行手机银行 App 时，三端均按建行 SDK 推荐做法回退建行 H5 网页支付，不阻断支付流程。
• provider: 'aggregate' 建行聚合支付：Android 使用 CcbMorePay，iOS 使用 payViewOrder；HarmonyOS 2.2 SDK 没有对应入口，会返回 9010002。
• 建行 SDK 不内置微信/支付宝客户端 SDK，插件已自行打包对应 SDK，无需额外引入微信开放平台 SDK。

配置总览

本插件包含 Android AAR/SO、iOS framework/静态库和 HarmonyOS HAR，真机运行必须制作包含本插件的自定义基座或使用云端打包；标准基座不包含这些原生 SDK。

先准备这些值：

按支付方式配置

龙支付：provider: 'ccb'

聚合支付：provider: 'aggregate'

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

微信支付：provider: 'wx'

支付宝支付：provider: 'alipay'

iOS 支付宝 App 回跳由插件生命周期 Hook 自动执行 AlipaySDK.processOrderWithPaymentResult，再交给建行 SDK 的 handleAliPayResult 查单；宿主仍必须正确配置订单串中的回跳 Scheme。

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. 配置 Associated Domains

在 HBuilderX manifest.json > iOS App配置 > 关联域（Associated Domains） 中添加：

applinks:<wxUniversalLink 的域名>

例如 Universal Link 为 https://pay.example.com/app/，关联域填写 applinks:pay.example.com。该域名还必须正确部署 apple-app-site-association，并与微信开放平台中配置的 Universal Link 完全匹配；关联域需要通过云端打包后生效。

4. 插件已声明

不要额外引入微信开放平台 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
})

harmonyWant 必须来自应用 EntryAbility 的 onCreate(want, launchParam)。插件初始化后会监听 onNewWant，并按建行文档把微信回跳 Want 传给微信 SDK；这条链路仍需在真实 HarmonyOS 设备上使用正式 AppID 完成验收。

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) // 仅 Android/iOS
startPayment('wx', orderInfo)
startPayment('alipay', orderInfo)

直接调用：

pay({ provider: 'ccb', orderInfo })
pay({ provider: 'aggregate', orderInfo }) // 仅 Android/iOS
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 可能包含“原始错误”。

测试说明

当前代码已通过 HBuilderX 5.14 的 Android 插件编译，以及 iOS、HarmonyOS standalone UTS 编译检查，但尚未使用真实商户 orderInfo 完成微信、支付宝付款及回跳验收，因此不能把编译通过等同于支付已成功。HarmonyOS 还未完成 DevEco/Hvigor 原生构建和真机支付验收；当前实现按建行 2.2 文档使用 SDKBuilder、WXBuilder、AliBuilder 和微信 Want 回跳链路。HarmonyOS 聚合支付因官方 SDK 没有对应入口而明确不支持。

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

• 正常支付成功后，客户端回调和服务端通知/查单结果一致。
• 用户取消支付时，业务侧不会误判为支付失败重试。
• 未安装目标支付 App、网络异常、订单重复、签名错误等异常场景能被正确处理。
• Android、iOS 使用到的渠道均以正式 AppID、签名和真实订单在真机完成回跳测试；具备 HarmonyOS 工具链和设备后，对实际使用的鸿蒙渠道执行同样验收。

支付方式选择说明

• provider: 'ccb' 是建行龙支付，支持建行 App 支付和建行 H5 网页支付兜底。未安装建行手机银行 App 时，会按建行 SDK 能力回退到建行 H5 支付页面。
• provider: 'aggregate' 是 Android/iOS 建行聚合支付，会进入建行聚合收银台；HarmonyOS 调用会返回 9010002。
• provider: 'wx' 是单独的微信 App 支付，需要安装微信并完成对应平台配置；插件不提供微信 H5 兜底。
• provider: 'alipay' 是单独的支付宝 App 支付，需要安装支付宝；插件不提供支付宝 H5 兜底。

如果业务希望“未安装支付 App 也能继续付款”，三端可使用建行龙支付；Android/iOS 还可使用建行聚合支付。服务端返回的 orderInfo 必须与对应支付方式匹配。

购买前说明

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

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