更新记录

1.0.0（2026-08-10）

1.0.0（2026-08-10）

• 首次以 tc-ysf-sdk 名称发布。
• 支持 Android 和 iOS 原生银联云闪付支付。
• 支持运行时配置 iOS 回跳 Scheme，不包含任何业务项目专属 Scheme。
• 统一 Android/iOS 支付结果回调接口。
• 补充 API 文档、快速接入示例、隐私说明和发布检查清单。

平台兼容性

uni-app(3.97)

uni-app x(3.97)

其他

银联云闪付支付 UTS SDK

tc-ysf-sdk 是一个基于银联原生支付 SDK 封装的 uni_modules UTS API 插件，可在 uni-app / uni-app x 的 Android 和 iOS App 中使用。

安全提醒：客户端回调只能用于更新界面，不能作为支付成功的最终依据。务必由业务服务端向支付渠道查询或接收异步通知，并以服务端结果更新订单。

功能

• Android 通过 UPPayAssistEx.startPayV2 发起银联支付。
• iOS 通过 UPPaymentControlMini 发起银联支付。
• Android 通过 Activity Result 返回原始支付结果。
• iOS 自动监听 URL Scheme 回跳并返回原始支付结果。
• 支持生产环境和银联测试环境。
• 不包含任何商户号、证书、密钥或业务服务端代码。

平台要求

• HBuilderX 3.97.0 或更高版本。
• 仅支持 App-Android、App-iOS，不支持 H5、小程序和 HarmonyOS。
• 插件包含原生 SDK、Manifest 和资源，调试时需要制作自定义基座；标准基座无法验证完整支付流程。
• tn 必须由业务服务端通过银联支付接口获取，不能在客户端生成。

安装

将插件目录放入项目：

你的项目/
└─ uni_modules/
   └─ tc-ysf-sdk/
      ├─ package.json
      └─ utssdk/

从插件市场安装时，HBuilderX 会自动放置到上述目录。

App 配置

iOS URL Scheme

在 manifest.json 的 App iOS 配置中，将 yourapp 换成应用自己的唯一 Scheme：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "urltypes": "yourapp",
        "urlschemewhitelist": "uppaysdk,uppaywallet,uppayx1,uppayx2,uppayx3,upwrp,uppay,uppayx,unionpay,yunshanfu"
      }
    }
  }
}

urltypes 中的值必须与调用 startYsfPay 时传入的 scheme 完全一致，且调用参数不要包含 ://。

如果项目已经配置其他 URL Scheme 或白名单，请在 HBuilderX 的可视化界面中合并配置，不要直接覆盖原值。

Android ABI

插件内置 armeabi-v7a 和 arm64-v8a 原生库。项目的 Android ABI 至少选择其中一种，例如：

{
  "app-plus": {
    "distribute": {
      "android": {
        "abiFilters": ["armeabi-v7a", "arm64-v8a"]
      }
    }
  }
}

快速使用

// #ifdef APP-PLUS
import {
  startYsfPay,
  setYsfReturnScheme,
  setYsfPaymentResultCallback,
  clearYsfPaymentResultCallback
} from '@/uni_modules/tc-ysf-sdk'
// #endif

const RETURN_SCHEME = 'yourapp'

export default {
  onLoad() {
    // #ifdef APP-PLUS
    setYsfReturnScheme(RETURN_SCHEME)
    setYsfPaymentResultCallback((result) => {
      console.log('银联客户端回调：', result.payResult, result.resultData)

      // 无论客户端返回什么，都应向业务服务端查询订单最终状态。
      this.queryOrderFromServer()
    })
    // #endif
  },

  onUnload() {
    // #ifdef APP-PLUS
    clearYsfPaymentResultCallback()
    // #endif
  },

  methods: {
    async pay() {
      // tn 必须由你的服务端返回。
      const tn = await this.requestTransactionNumberFromServer()

      // 00：生产环境；01：银联测试环境。
      const accepted = startYsfPay(tn, RETURN_SCHEME, '00')
      if (!accepted) {
        uni.showToast({ title: '支付启动失败', icon: 'none' })
      }
    }
  }
}

完整页面示例见 examples/basic-pay.vue。

API

startYsfPay(tn, scheme, mode): boolean

发起原生银联支付。

返回值仅表示原生支付启动请求是否被接受，不表示支付成功。

setYsfReturnScheme(scheme): void

配置 iOS 回跳 Scheme。建议页面初始化时调用一次。Android 端是空实现，跨端调用不会报错。

setYsfPaymentResultCallback(callback): void

注册支付结果监听器。结果结构：

type YsfPaymentResult = {
  payResult: string
  resultData: string
}

• Android：payResult 对应 SDK 的 pay_result，常见值为 success、fail、cancel；resultData 对应 result_data。
• iOS：payResult 对应 SDK 完成回调的 code，resultData 是回调数据序列化后的 JSON 字符串。
• 不同 SDK 版本可能返回不同文本，请将它们当作原始值处理。

clearYsfPaymentResultCallback(): void

清除监听器。页面销毁时调用，避免页面实例被长期引用。

更多说明见 API.md。

建议接入流程

1. App 请求业务服务端创建支付订单。
2. 服务端调用支付渠道获取 tn 并返回 App。
3. App 调用 startYsfPay 拉起云闪付或银联收银台。
4. 客户端收到回调后显示“结果确认中”。
5. App 向业务服务端查询订单状态。
6. 服务端依据支付渠道异步通知或主动查询结果确认订单。

常见问题

标准基座中调用失败

插件包含 Android JAR/SO、Manifest 以及 iOS XCFramework，需要制作自定义基座或云端打正式包后测试。

iOS 支付后没有回到 App

检查以下三项是否完全一致：

1. manifest.json 中 iOS 的 urltypes。
2. setYsfReturnScheme() 的参数。
3. startYsfPay() 的第二个参数。

参数只传 Scheme 名，例如 yourapp，不要传 yourapp://。

收到 success 是否可以直接发货

不可以。客户端环境不可作为可信支付凭据，必须以服务端查单或支付渠道异步通知为准。

Android 没有安装云闪付怎么办

银联 SDK 会依据终端环境决定可用路径。具体行为取决于所集成的银联 SDK 版本和终端钱包环境，业务侧仍应做好启动失败提示与订单状态恢复。

隐私与合规

• 插件封装代码不主动采集、存储或上传用户信息。
• 插件包含银联原生 SDK，其实际数据处理、合规披露和隐私政策应以银联官方材料为准。
• iOS SDK 自带隐私清单文件；发布者仍需根据实际 App 功能完善应用隐私政策、应用商店隐私标签及合规弹窗。
• Android 声明 INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE 权限。

第三方 SDK 与授权

插件封装代码与银联原生二进制采用不同授权。发布到插件市场前，请确认你有权重新分发包内的银联 SDK 文件，并确认 SDK 版本符合银联当前接入要求。详情见 license.md 和 THIRD_PARTY_NOTICES.md。

更新日志

见 changelog.md。