更新记录

1.0.0（2026-06-03）

1.插件的第一次发布，鸿蒙没有做真机测测试

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-unionpay

【Android + iOS + Harmony】银联云闪付支付插件，基于银联支付控件 TN 模式，三平台统一接口。

注意：本插件仅支持 TN 模式（银联原生支付控件），不支持 Direct 直连模式。

目录

• 快速开始
• API 参考
• 平台集成
• 类型定义
• 错误码
• 安全建议

快速开始

安装

将 tt-unionpay 目录放入项目的 uni_modules/ 下。

使用

import * as unionpay from "@/uni_modules/tt-unionpay"

const up = unionpay.getTTUnionPaySDK()

// 1. 初始化
up.register({
    env: "00",                        // "00": 生产环境  "01": 测试环境
    urlScheme: "your-app-scheme",     // iOS / Harmony 的 URL Scheme
    success: () => {
        console.log("初始化成功")
    },
    fail: (err) => {
        console.error("初始化失败:", err.errMsg)
    }
})

// 2. 检查是否安装云闪付
if (up.isInstall()) {
    // 3. 发起支付（TN 模式）
    up.pay({
        mode: "tn",
        tn: "20260511000000001",      // 服务端返回的交易流水号
        success: (res) => {
            if (res.code === "success") {
                console.log("支付成功", res.rawData)
            } else if (res.code === "cancel") {
                console.log("用户取消")
            }
        },
        fail: (err) => {
            console.error("支付失败:", err.errCode, err.errMsg)
        },
        complete: (res) => {
            console.log("支付流程结束")
        }
    })
} else {
    console.log("未安装云闪付 App")
}

API 参考

getTTUnionPaySDK()

获取 SDK 实例，单例模式。

const up = unionpay.getTTUnionPaySDK()

isInstall()

检查是否安装了云闪付 App。

up.isInstall(): boolean

register(options)

初始化支付配置，建议在 App 启动后尽早调用。

up.register(options: TTUnionPayRegisterOptions): void

pay(options)

发起 TN 模式支付。

up.pay(options: TTUnionPayPayOptions): void

平台集成

Android

Manifest 配置

在项目 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.INTERNET" />

<application android:usesCleartextTraffic="true">
    <activity
        android:name="com.unionpay.uppay.PayActivity"
        android:exported="false"
        android:launchMode="singleTask"
        android:screenOrientation="portrait" />
</application>

回调处理

在 MainActivity 中转发 onActivityResult：

import { handleActivityResult } from "@/uni_modules/tt-unionpay"

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    handleActivityResult(requestCode, resultCode, data)
}

iOS

Info.plist 配置

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YourAppScheme</string>
        </array>
    </dict>
</array>

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>uppaywallet</string>
    <string>uppayx</string>
    <string>uppay</string>
</array>

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

回调处理

插件内置 UnionPayHookProxy，自动拦截支付回调 URL，无需额外代码。

Harmony

回调处理

在 EntryAbility 的 onNewWant 中转发：

import { handleWant } from "@/uni_modules/tt-unionpay"

export default class EntryAbility extends UIAbility {
    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        handleWant(want)
    }
}

类型定义

TTUnionPayPaySuccess

支付成功回调参数：

TTUnionPayPayFail

支付失败回调参数（IUniError）：

平台差异

错误码

安全建议

1. 服务端下单：TN 由服务端向银联下单后返回，客户端不持有商户密钥
2. 异步通知确认：支付成功回调仅表示客户端收到结果，最终状态建议通过服务端 notifyUrl 确认
3. 订单幂等：使用唯一订单号，防止重复支付
4. 生产环境验证：切换 env: "00" 前完成测试环境验证