更新记录

1.0.0（2026-11-07）

• 首次发布，支持 Android、iOS 和 HarmonyOS NEXT 银联 TN 支付，内置银联官方 SDK。
• 统一支付回调和错误码，支持支付回跳并防止重复发起支付。

平台兼容性

uni-app(4.86)

uni-app x(4.86)

其他

umi-unionpay

银联官方「线上收银台（通用版）」TN 支付 UTS API 插件。Android、iOS、HarmonyOS NEXT 分平台实现，共享强类型参数、结果和会话控制。接口为 unionPay，通过 import 调用，不使用 uni.requireNativePlugin。

SDK 与运行要求

HBuilderX 4.61+。三端原生依赖均已放入插件，无需从第三方镜像下载；请使用自定义基座/原生发行构建。标准基座不包含这些 SDK。插件使用未经修改的银联官方 SDK。Harmony 使用 UTS 内置的 UTSHarmony，由编译器按宿主注入正确的运行时包。

本次完成 UTS 三端转换和逻辑测试，尚未完成三端原生构建、链接和真机支付。平台清单保留待验证标记，不作为插件市场已验证兼容性的声明。项目当前启用 vapor，原生构建还需验证相应 HBuilderX 版本的 vapor 插件兼容性。

调用

import { unionPay, UnionPayOptions, UnionPayResult } from '@/uni_modules/umi-unionpay'

const options: UnionPayOptions = {
  tn: tnFromYourServer,
  mode: '01',
  scheme: 'yourappscheme',
  success: (res: UnionPayResult): void => {
    // SDK 报告成功；向商户服务端查单，服务端确认后再发货。
    console.log(res.code)
  },
  fail: (res: UnionPayResult): void => {
    console.log(res.errCode, res.errMsg)
  },
  complete: (_res: UnionPayResult): void => {
    // 关闭 loading。
  }
}
unionPay(options)

工程根目录下的 examples/pay.uts 提供完整函数示例。TN、商户证书、签名和支付金额应由商户服务端处理，不要把私钥放入客户端。客户端不请求第三方测试 TN 地址。

isUnionPaySupported() 仅判断当前编译平台是否实现此插件，不探测 SDK 链接、钱包安装或商户配置。Web/小程序等平台返回 false，调用支付返回 9010007。

Android 配置

插件已经包含 JAR、arm64-v8a / armeabi-v7a / x86 / x86_64 SO、网络权限、UPPayWapActivity、支付 App queries，以及 dialogTheme。宿主选择的 ABI 必须与插件匹配。官方旧 armeabi 库未集成。

SDK 使用 UPConstant.KEY_TN、KEY_MODE、KEY_SE_TYPE、KEY_SIGN_DATA 填充 Bundle，通过 startPayV2 调起。仅消费携带 pay_result 的 Activity Result；返回值非 0 时报告启动失败。成功、失败和取消时移除监听，避免影响其他插件。

离线 Android 工程如开启 R8/ProGuard，应将 utssdk/app-android/proguard-rules.pro 内容合入应用实际使用的混淆规则。该文件作为规则来源提供，不假设 HBuilderX 会自动合并。对银行 App 的 queries 已按下载包指南列出，后续支付工具变化时需同步官方列表。

iOS 配置

1. 将工程根目录下的 examples/ios-scheme.plist 中的 yourappscheme 改为自己的唯一 Scheme，将字典内容合入宿主项目根目录的 Info.plist（或使用宿主对应的 URL Types 配置）。已有 URL Types 应合并保留。
2. 调用 unionPay 时传入完全相同的 Scheme。插件启动前会检查实际打包进应用的 CFBundleURLTypes。
3. 插件 Info.plist 已声明银联基础查询白名单：uppaysdk、uppaywallet、uppayx1、uppayx2、uppayx3。若启用银行 App 直通，请依官方指南补充所需银行 Scheme，并与其他插件白名单合并。
4. 系统库和 XCFramework 已在插件内配置。测试环境如确实需要 HTTP，由宿主按官方指南添加测试用 ATS 配置，发布时移除；插件不全局放开 ATS。

UTS 的 UnionPayHookProxy 自动接收 applicationOpenURLOptions，回跳交由官方 SDK 解析；薄层 Swift 只负责 Objective-C 接口、主线程调度和字典转 JSON。iOS 官方此版本接口不接受 seType/signData，传入非空值将报参数错误，避免静默丢弃。

HarmonyOS NEXT 配置

HAR 已作为本地依赖配置为 libuppayment: ./libs/libuppayment.har。宿主还需配置 EntryAbility 的回跳和支付工具查询名单：

1. 初次运行/构建后，将生成的 entry/src/main/module.json5 完整复制到项目 harmony-configs/entry/src/main/module.json5。
2. 参考工程根目录下的 examples/harmony-module.fragment.json，将 INTERNET、querySchemes、回跳 skill 合入完整文件。这个示例只是片段，不能直接覆盖完整模块配置。
3. Scheme 改为自己的唯一值，并与支付参数一致。回跳 skill 的 actions 包含 action.uppay.open，uri host 为 uppayresult。保留原有首页 skill 和其他配置。
4. 如支持其他银行工具，按官方指南补充 querySchemes（注意平台总数量限制）；SDK 的可用渠道取决于当前银联服务配置及终端环境。

插件通过 UTSHarmony 获取 UIAbilityContext，监听 onAppAbilityNewWant / onAppAbilityCreate，将结果交给同一个 UPPayment 实例解析，使用官方 UPPayResultStatus 映射返回状态。

结果与恢复

UnionPayResult 包含 errSubject: 'umi-unionpay'、errCode、errMsg、code、data。code 保留 SDK 的 success/fail/cancel，未识别结果走错误分支；data 是 SDK 结果数据，iOS 字典转为 JSON 字符串，Android/Harmony 为原始字符串。

会话互斥，回调前先释放会话；同一会话重复结果不重复通知，已经捕获的旧 SDK 回调不会结束后续会话。success/fail 中抛出异常时仍尝试调用 complete。URL Scheme 和 uppayresult 过滤仅用于路由，不能代替支付验签或服务端查单。

handleUnionPayURL(url): boolean 可供宿主手动转发当前会话的 URL。正常暖启动自动接收，无需重复转发。没有当前会话、无关 URL 或已在解析的 URL 返回 false；Android 使用 Activity Result，此方法返回 false。

应用进程被系统结束后，原来的 JS/UTS 回调不可能恢复；宿主需持久化业务订单号，在重新启动或回到前台时向服务端查询未完成订单。未收到 SDK 回调时插件保持互斥，不自动超时释放，以免迟到回执串到新订单。不要把缺失回调、返回前台或本地超时当成支付失败或成功。外部重复 URL 可能无法从 SDK 报文可靠关联到 TN，业务最终状态始终以服务端为准。

验证

已验证：Kotlin/Swift/ArkTS 的完整 UTS bundle 转换；公共参数、互斥、结果映射、URL 过滤、回调异常处理；Android 包装层的启动参数、无关事件、旧回调和启动失败清理。UTS 转换使用本地 HBuilderX 编译器，原生类型检查和链接仍需验证。Android 包装层测试使用模拟的原生依赖。

待真机验证：三端自定义基座构建/链接，测试 TN 的成功/失败/取消，无钱包及不同钱包版本，支付回跳、冷启动查单恢复，签名包及正式环境。当前环境未执行云打包或真实支付。

官方资料

• 银联线上收银台（通用版）与 SDK 下载
• 银联 SDK 隐私政策入口

插件本身不采集支付信息，不打印 TN/签名。银联 SDK 的数据处理、隐私说明和使用条件以官方材料为准；请在宿主隐私政策中披露实际集成的 SDK。