更新记录

1.0.0（2026-04-24）

支持 stripe支付

平台兼容性

uni-app(4.87)

uni-app x(4.87)

tt-stripe-pay

💳 Stripe PaymentSheet 插件，为 uni-app / uni-app x 提供原生收银台能力（银行卡等），在 iOS、Android App 上调起 Stripe 预置 UI，配合服务端 PaymentIntent 完成收款。

📖 目录

• SDK 版本信息
• 重要提示
• 环境配置
• 快速开始
• 基础使用
• API 文档
• 官方演示数据（联调）
• 错误码
• 常见问题

SDK 版本信息

• iOS：23.28.3，deploymentTarget 13
• Android：20.48.0，minSdkVersion 21

重要提示

⚠️ 建议使用自定义基座或正式包，在 真机 上调试支付；模拟器部分能力受限。

⚠️ 客户端 success 仅表示 PaymentSheet 流程结束；是否到账请以 服务端查询 PaymentIntent 或 Webhook（如 payment_intent.succeeded）为准。

⚠️ iOS 若用户会跳到 Safari / 银行 App 鉴权，必须配置 自定义 URL Scheme、returnURL，并挂载 TTStripePayHookProxy（见 环境配置 - iOS 回跳）。

环境配置

前置条件

1. Stripe Dashboard 开通账号，配置 支付方式。
2. 服务端：使用 Secret Key 创建 PaymentIntent，将 client_secret 与 Publishable Key（可下发给客户端）返回给 App。
3. App 内使用服务端下发的 Publishable Key，在 presentPaymentSheet 中与 client_secret 一并传入（须同属一套账号与环境）。

iOS 回跳（return URL + URL Scheme）

与 Web 版 Checkout 的 success_url / return_url 不是同一套。原生 PaymentSheet 要求：

1. 在插件内配置 URL Scheme
   编辑 uni_modules/tt-stripe-pay/utssdk/app-ios/Info.plist 中的 CFBundleURLSchemes：须与调用 presentPaymentSheet 时传入的 returnURL 的 scheme 一致（例如 returnURL 为 myapp://stripe-redirect，则此处需包含 myapp）。 插件默认带有 payments-example，与 官方演示 的 payments-example://stripe-redirect 一致；正式环境请改为或追加你的自有 scheme。
2. 调起支付时传入 returnURL（完整 URL，含 scheme / host / path），与 PaymentSheet.Configuration.returnURL 一致。

📚 官方说明：Set up a return URL（Stripe 文档写明 不支持 用 Universal Links 替代该自定义 Scheme 回跳。）

仅银行卡、无需跳出 App

若仅测试 无需外跳 的卡支付，可暂不设置 returnURL；一旦启用可能外跳的支付方式，请按上文补齐。

快速开始

1. 导入插件

uni-app x（script setup + lang="uts"）

import { getTTStripePay } from '@/uni_modules/tt-stripe-pay';

const stripePay = getTTStripePay();

uni-app（Vue3）

import { getTTStripePay } from '@/uni_modules/tt-stripe-pay';

const stripePay = getTTStripePay();

类型定义可从 utssdk/interface.uts 对照；业务侧可按需 import type { ... } from '@/uni_modules/tt-stripe-pay/utssdk/interface'（路径以工程为准）。

2. 条件编译（推荐）

仅 App-Android / App-iOS 引用，避免编译到小程序与 H5：

// #ifdef APP-ANDROID || APP-IOS
import { getTTStripePay } from '@/uni_modules/tt-stripe-pay';
// #endif

基础使用

流程：服务端拿到 publishableKey + client_secret → 一次调用 presentPaymentSheet({ publishableKey, paymentIntentClientSecret, ... })（内部会先写入 Key 再调起收银台）。

示例（uni-app x）

const stripePay = getTTStripePay();

stripePay.presentPaymentSheet({
    publishableKey: 'pk_test_xxx',
    paymentIntentClientSecret: 'pi_xxx_secret_xxx',
    merchantDisplayName: '我的商户',
    returnURL: 'myapp://stripe-redirect', // iOS 外跳支付时建议填写，并与 URL Scheme 一致
    customerId: 'cus_xxx', // PI 若关联 Customer，须与 customerEphemeralKeySecret 成对传入（官方演示后端会返回）
    customerEphemeralKeySecret: 'ek_test_xxx',
    success: (_res) => {
        console.log('流程完成，仍建议服务端查 PaymentIntent');
    },
    fail: (err) => {
        console.error(err.errCode, err.errMsg);
    },
    complete: null,
});

API 文档

getTTStripePay

type GetTTStripePay = () => TTStripePay;

返回单例式 TTStripePay 接口实现。

TTStripePay.presentPaymentSheet

调起 PaymentSheet。会先写入 publishableKey（iOS：STPAPIClient；Android：PaymentConfiguration.init），再展示 UI。须保证当前页面可取得 UIViewController（iOS）或 Activity（Android）。

参数 TTStripePresentPaymentSheetOptions

官方演示数据（联调）

stripe-ios 的 PaymentSheet Example 使用演示后端（与 ExampleCheckoutViewController.swift 中 backendCheckoutUrl 一致）：

• URL：https://stripe-mobile-payment-sheet.stripedemos.com/checkout
• 方法：POST
• 响应字段：publishableKey、paymentIntent（即 client secret）等

tt-stripe-demo 示例页提供「拉取官方演示数据」按钮，可快速填入上述字段；演示用 returnURL 为 payments-example://stripe-redirect，需在 iOS 配置 Scheme payments-example。正式环境请使用自有服务端，勿依赖演示站。

错误码

errSubject 为 TTStripePay 时常见 errCode：

常见问题

Q：iOS 点击调起收银台立刻崩溃？
A：多为 PaymentIntent 在服务端关联了 Customer，但客户端未传入 customerId + customerEphemeralKeySecret，Stripe SDK 会断言失败。tt-stripe-demo 里点「拉取官方演示数据」会把这两项一并填入；自有服务端若创建带 Customer 的 PI，也需同样下发并在 presentPaymentSheet 里成对传入。

Q：为什么文档里写了 return_url，插件里没有 Web 那种页面地址？
A：那是 网页 / Stripe.js 或 Checkout Session 的跳转地址。本插件走的是 原生 PaymentSheet，iOS 使用 returnURL + URL Scheme + StripeAPI.handleURLCallback，见 官方 Set up a return URL。

Q：能否只在客户端完成收款？
A：不能。PaymentIntent 必须由服务端创建；客户端只用 client secret + publishable key 完成 SDK 展示与确认，否则密钥泄露且不符合 Stripe 安全模型。

Q：支付成功就一定到账吗？
A：不一定。请以服务端 PaymentIntent 状态 与 Webhook 为准；部分支付方式为延迟通知（若开启 allowsDelayedPaymentMethods 相关能力，更需依赖服务端事件）。

Q：Android 云打包报 Could not find stripe-android-… / Failed to transform … stripe-android？
A：多为 镜像未同步 Stripe 子模块（尤其 23.x 的 paymentsheet）。请使用当前插件默认的 stripe-android:20.48.0；若自行升级到 23.x，需云打包能访问 Maven Central 或镜像已补全对应 paymentsheet 版本。