更新记录

v1.0.0（2026-08-02） 下载此版本

1.0.0

• 支持 Android 端 TN 模式拉起银联支付控件。
• 支持 iOS 端 TN 模式拉起支付及 URL Scheme 回调。
• 支持 success、fail、cancel、unknown 统一结果。
• 内置 Android 包可见性、网络权限和银联 WAP Activity 配置。
• 内置 iOS Swift module map。

平台兼容性

uni-app(5.04)

hxd-unionpay

用于 uni-app App 端的银联云闪付 UTS 支付插件。插件封装中国银联官方 Android 3.5.16 和 iOS 3.6.2 Mini 支付控件，通过服务端返回的 TN 拉起云闪付或受支持的银行支付 App。

平台支持

插件包含原生 SDK，必须制作自定义调试基座或云打包，标准运行基座无法使用。

安装

将插件目录放入项目：

uni_modules/hxd-unionpay

如果项目源码位于 src，则放入：

src/uni_modules/hxd-unionpay

服务端要求

服务端必须完成银联 App 支付下单并向前端返回 TN。TN 通常是 21 位数字，例如：

868200869025887744100

插件不负责生成 TN、签名、验签、退款或订单查询。

iOS 配置

在 manifest.json 的 app-plus.distribute.ios 中注册回跳 Scheme，并加入银联 Scheme 白名单：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "urltypes": "unionpayuts",
        "urlschemewhitelist": "uppaywallet,uppaysdk,uppayx1,uppayx2,uppayx3"
      }
    }
  }
}

urltypes 必须与调用 startPay 时传入的 scheme 完全一致。正式项目建议使用与 Bundle ID 相关的唯一小写 Scheme，避免与其他 App 冲突。

基础调用

仅在 App 条件编译中导入：

// #ifdef APP-PLUS
import { startPay } from '@/uni_modules/hxd-unionpay'
// #endif

调用支付：

// #ifdef APP-PLUS
startPay({
  tn: '868200869025887744100',
  mode: '00',
  scheme: 'unionpayuts',
  success: result => {
    console.log('银联控件返回成功', result)
  },
  fail: result => {
    console.error('支付失败或取消', result)
  },
  complete: result => {
    console.log('支付控件已返回', result)
    // 无论客户端返回什么，都应调用服务端订单查询接口确认最终状态。
    queryOrderStatus()
  }
})
// #endif

Promise 封装示例

// #ifdef APP-PLUS
const payByUnionPay = (tn: string) =>
  new Promise<void>((resolve, reject) => {
    if (!/^\d{21}$/.test(tn)) {
      reject(new Error('银联 TN 格式错误'))
      return
    }

    startPay({
      tn,
      mode: '00',
      scheme: 'unionpayuts',
      success: () => resolve(),
      fail: result => reject(new Error(result.message)),
      complete: () => {
        void queryOrderStatus()
      }
    })
  })
// #endif

参数

startPay(options)

返回结果

type UnionPayResult = {
  code: 'success' | 'fail' | 'cancel' | 'unknown'
  message: string
  rawCode?: string
}

支付结果安全

客户端回调只能表示支付控件返回结果，不能作为订单支付成功的最终凭证。正确流程：

1. App 获取服务端生成的 TN。
2. 插件拉起银联支付控件。
3. 控件返回后 App 调用服务端查单接口。
4. 只有服务端确认支付成功后，才能发货、充值或跳转支付成功页。

常见问题

Android 提示未安装云闪付

1. 重新制作包含插件的自定义基座，普通热更新不会更新 AndroidManifest。
2. 确认安装的是正式云闪付 App，而不是分身、冻结或定制版本。
3. 查看控制台日志中的 walletInstalled 和 startPayResult。
4. 使用银联官方 Demo 和相同 TN 测试，排除商户通道或 TN 配置问题。

iOS 无法回到 App

检查 manifest.json 的 urltypes 是否与 startPay 的 scheme 一致，并重新云打包。

支付成功但没有回调

App 可能在支付期间被系统回收。页面重新进入或 onShow 时应主动调用服务端查单接口，不能只依赖 SDK 回调。

发布与合规说明

• 插件调用中国银联官方 SDK，不代表插件作者是中国银联官方或获得官方背书。
• 发布前请确认你有权随插件分发银联 SDK 二进制文件。
• 接入方应根据银联最新文档补充隐私政策、第三方 SDK 清单和数据处理说明。
• 银联 SDK 版本、权限和隐私规则可能更新，生产使用前应重新核对官方资料。