更新记录

1.0.0（2026-04-10）

苹果支付功能

平台兼容性

uni-app(4.86)

uni-app x(4.86)

tt-apple-pay

💳 Apple Pay SDK 插件，为 uni-app / uni-app x 提供基于 PassKit 的 Apple Pay 集成：调起系统收银台，返回支付令牌供服务端解密扣款。

📖 目录

• 务必先读：这是 Apple Pay，不是应用内购（IAP）
• SDK 版本信息
• 环境配置
• 快速开始
• 基础使用
• API 文档
• 错误处理
• 常见问题

⛔ 务必先读：这是 Apple Pay，不是应用内购（IAP）

若你的需求是在 App 内购买虚拟商品，请不要使用本插件，应使用 StoreKit 应用内购买。DCloud 插件市场提供对应 UTS 插件：

👉 苹果内购插件（插件 ID：26906，tt-apple-iap）

Apple Pay 与 IAP 名称里都带 “Apple”，但产品形态与审核要求完全不同；用错方案会导致功能无法实现或 无法通过 App Store 审核。

SDK 版本信息

📚 推荐阅读: Apple 官方文档 - Apple Pay · PKPaymentToken

🚨 重要提示

⚠️ 再次强调：本插件是 Apple Pay（PassKit），不是 StoreKit 应用内购。虚拟商品请使用 苹果内购插件（26906）。

⚠️ 建议使用自定义基座或正式包真机调试，并正确配置 Merchant ID、描述文件与 Apple Pay 能力。

⚠️ 仅支持 iOS 平台，与其他平台同时运行建议加条件编译。

环境配置

前置条件

1. 在 Apple Developer 中创建 Merchant ID（如 merchant.com.example.app），并为 App ID 启用 Apple Pay、关联该 Merchant ID。
2. 重新生成并下载 Provisioning Profile，在 HBuilderX / Xcode 中更新签名与描述文件。
3. iOS 系统版本 13.0 及以上。

Apple Developer 配置

1. Merchant ID 与 Apple Pay

1. 登录 Apple Developer Portal
2. 进入 Certificates, Identifiers & Profiles
3. 在 Identifiers 中创建或选择 Merchant IDs，记下 Merchant ID 字符串
4. 选择你的 App ID，编辑并勾选 Apple Pay，绑定上述 Merchant ID
5. 保存配置

2. 更新描述文件

启用 Apple Pay 后，须在 Provisioning Profiles 中重新生成描述文件并下载，再在本地工程中更新。

插件内配置

1. 编辑本插件 utssdk/app-ios/UTS.entitlements，将 com.apple.developer.in-app-payments 数组中的占位符改为你的 Merchant ID。
2. 用 Xcode 打开 App 原生工程，在 Signing & Capabilities 中添加 Apple Pay，勾选同一 Merchant ID。

重要注意事项

💡 paymentData：成功回调中的 paymentData 为 Base64，须由服务端按 Apple 文档解密并与支付网关交互，切勿仅在客户端处理敏感逻辑。

💡 summaryItems：最后一项为应付总额；若有多行明细，前面各项金额之和须与最后一项一致。

⚠️ 沙盒与真机：测试需在已登录 Wallet、具备测试卡或真实卡环境的真机上进行。

快速开始

1. 导入插件

import * as applePay from "@/uni_modules/tt-apple-pay";

export default {
    data() {
        return {
            applePayImpl: null as applePay.TTApplePay | null,
        }
    },
    onLoad() {
        this.applePayImpl = applePay.getApplePay();
    },
    methods: {
        handleApplePay() {
            // 见下方「基础使用」「API 文档」
        }
    }
}

2. 条件编译

由于 Apple Pay 仅支持 iOS，建议使用条件编译：

// #ifdef APP-IOS
import * as applePay from "@/uni_modules/tt-apple-pay";
// #endif

export default {
    data() {
        return {
            // #ifdef APP-IOS
            applePayImpl: null as applePay.TTApplePay | null,
            // #endif
        }
    },
    onLoad() {
        // #ifdef APP-IOS
        this.applePayImpl = applePay.getApplePay();
        // #endif
    }
}

3. 示例页面

本仓库提供示例页 pages/index/index.uvue（若随 Demo 工程引入）：请将其中 MERCHANT_ID 改为你的 Merchant ID 后运行。

基础使用

平台检测

checkPlatformSupport(): boolean {
    // #ifndef APP-IOS
    uni.showModal({
        title: '平台不支持',
        content: 'Apple Pay 仅支持 iOS App',
        showCancel: false
    });
    return false;
    // #endif
    return true;
}

检测设备是否可用 Apple Pay

// #ifdef APP-IOS
const ok = this.applePayImpl!.canMakePayments(["visa", "masterCard", "amex", "chinaUnionPay"]);
// 传入 null 或 [] 时，仅调用系统 canMakePayments()，不区分卡组织
const ok2 = this.applePayImpl!.canMakePayments(null);
// #endif

API 文档

getApplePay()

返回 TTApplePay 实例，可保存在 data 中复用。

canMakePayments(supportedNetworks)

返回值：boolean，同步返回。

requestPayment(options)

参数说明（TTApplePayRequestPaymentOptions）

TTApplePaySummaryItem

supportedNetworks 常用值（建议小写）：visa、masterCard、amex、discover、chinaUnionPay、interac、maestro、privatelabel 等，完整映射见源码 TTApplePayProvider.swift。

merchantCapabilities（可选）：如 ["3DS", "credit", "debit", "emv"]，其中 3DS 对应 threeDSecure。

示例代码

// #ifdef APP-IOS
this.applePayImpl?.requestPayment({
    merchantIdentifier: "merchant.com.example.app",
    countryCode: "CN",
    currencyCode: "CNY",
    supportedNetworks: ["visa", "masterCard", "amex", "chinaUnionPay"],
    merchantCapabilities: null,
    summaryItems: [
        { label: "商品 A", amount: "6.00" },
        { label: "运费", amount: "3.00" },
        { label: "商户名称", amount: "9.00" },
    ],
    success: (result) => {
        console.log("✅ Apple Pay 授权成功:", result);
        this.handlePaySuccess(result);
    },
    fail: (error) => {
        console.error("❌ Apple Pay 失败:", error);
        this.handlePayError(error);
    },
    complete: null,
} as applePay.TTApplePayRequestPaymentOptions);
// #endif

// #ifndef APP-IOS
uni.showModal({
    title: '平台不支持',
    content: 'Apple Pay 仅支持 iOS 平台',
    showCancel: false
});
// #endif

将令牌交给服务端（示意）

handlePaySuccess(result: applePay.TTApplePayPaymentSuccess) {
    uni.request({
        url: 'https://your-server.com/api/apple-pay/charge',
        method: 'POST',
        data: {
            paymentData: result.paymentData,
            transactionIdentifier: result.transactionIdentifier,
            paymentMethod: result.paymentMethod,
        },
        success: (res) => {
            console.log('服务端处理成功:', res.data);
            uni.showToast({ title: '支付成功', icon: 'success' });
        },
        fail: (err) => {
            console.error('服务端失败:', err);
            uni.showToast({ title: '订单确认失败', icon: 'none' });
        }
    });
}

返回值说明

TTApplePayPaymentSuccess

TTApplePayPaymentMethodInfo

错误处理

插件错误码

错误处理最佳实践

handlePayError(error: any) {
    console.error('❌ Apple Pay 失败:', error);
    const errCode = error.errCode;
    const errMsg = error.errMsg;

    switch (errCode) {
        case 201:
            console.log('用户取消支付');
            return;
        case 104:
            uni.showModal({
                title: '无法使用 Apple Pay',
                content: '请检查是否已添加银行卡或商户配置是否正确',
                showCancel: false
            });
            break;
        case 100:
        case 101:
            uni.showToast({ title: errMsg || '参数错误', icon: 'none' });
            break;
        default:
            uni.showToast({ title: errMsg || '支付失败', icon: 'none' });
            break;
    }
}

常见问题

1. 和「苹果内购 / IAP」有什么区别？

本插件只做 Apple Pay（银行卡类支付令牌）。要在 App 里卖 虚拟商品、订阅，必须用 IAP，请使用 DCloud 插件：苹果内购（26906）。

2. 自定义基座或真机调试？

说明：Apple Pay 依赖真机、正确签名与 Merchant 配置；请使用与证书一致的自定义基座或正式包在真机上验证。

3. 打包失败或支付界面调不起？

解决方案：

• 确认 Apple Developer 中 App ID 已启用 Apple Pay 且绑定 Merchant ID
• UTS.entitlements 与 Xcode Capability 中 Merchant ID 一致
• 重新生成描述文件并在工程中更新

4. 其他平台如何兼容？

解决方案：

• 使用 #ifdef APP-IOS 引入插件与调用支付
• 为非 iOS 用户提供微信、支付宝等其他支付方式

5. paymentData 如何使用？

解决方案：将 Base64 的 paymentData 原样或按网关要求 POST 到自有服务端，由服务端使用支付服务商 / Apple 文档完成解密与扣款，不要在客户端保存或拼接密钥。

6. 金额或账单展示异常？

解决方案：保证 summaryItems 最后一项为总金额；多行时前面各行金额之和等于最后一项；amount 使用字符串形式的十进制数（如 "10.00"）。

技术支持

如在集成过程中遇到问题，请：

1. 查阅上方「常见问题」与错误码表
2. 对照 Apple Pay 编程指南
3. 核对 Merchant ID、证书、描述文件与 Xcode Capabilities

祝您开发愉快！ 🎉