用 PaymentSheet 类将 Stripe 的预构建支付 UI 集成到您的 Android 应用程序的结账流程。
设置 Stripe 首先,您需要有 Stripe 账户。立即注册 。
Server-side 该集成要求您的服务器上的端点与 Stripe API 通讯。请用官方库从您的服务器访问 Stripe API:
Client-side Stripe Android SDK 是开源的,且有完整的文档 。
安装 SDK 时,将 stripe-android
添加到您的 app/build.gradle 文件的 dependencies
块中:
plugins {
id ( "com.android.application" )
}
android { .. . }
dependencies {
implementation ( "com.stripe:stripe-android:21.28.0" )
implementation ( "com.stripe:financial-connections:21.28.0" )
}
注意 有关最新 SDK 发布及过往版本的详细信息,请查看 GitHub 上的发布 页面。要想在新版本发布时接收通知,请查看仓库的发布情况 。
该集成使用三个 Stripe API 对象:
PaymentIntent :Stripe 用它来表示您从客户收款的意图,跟踪您的扣款尝试及整个过程中付款状态的变化情况。
(可选)Customer :要为将来的付款设置支付方式,就必须将它绑定到 Customer 。当客户在您的公司创建账户时,创建 Customer 对象。如果您的客户以访客身份付款,则可以在付款前创建个 Customer 对象,然后再将它关联到您自己内部的客户账户表示。
(可选)Customer Ephemeral Key:Customer 对象的信息属于敏感信息,无法直接从应用中检索。临时密钥授予 SDK 对客户的临时访问权限。
注意 如果您从不将银行卡保存到客户,并且不允许回头客重复使用已保存的银行卡,则可以从集成中省略 Customer 和 Customer Ephemeral Key 对象。
出于安全原因,您的应用无法创建这些对象。相反,在服务器上会添加一个端点,其功能如下:
检索 Customer,或新建一个。 为 Customer 创建一个 Ephemeral Key。 创建 PaymentIntent,设置好 amount 、currency 和 customer 。您还可以选择包含 automatic_ payment_ methods
参数。默认情况下,Stripe 会在最新版的 API 中启用其功能。 将 Payment Intent 的客户端私钥 、Ephemeral Key 的 secret
以及 Customer 的 id 和您的公钥 返回到您的应用程序。 在结账过程中显示给客户的支付方式也包含在 PaymentIntent 中。您可以让 Stripe 从管理平台设置中提取支付方式,也可以手动列出它们。无论选择哪种方式,都要知道在 PaymentIntent 中传递的货币会过滤显示给客户的支付方式。例如,如果您在 PaymentIntent 中传递 eur
,并且在管理平台中启用了 OXXO,则不会向客户显示 OXXO,因为 OXXO 不支持 eur
支付。
除非您的集成需要基于代码的选项来提供支付方式,否则 Stripe 建议使用自动选项。这是因为 Stripe 会评估货币、支付方式限制和其他参数,以确定支持的支付方式列表。优先显示可提高转化率且与货币和客户所在地最相关的支付方式。
您可以从管理平台 管理支付方式。Stripe 根据交易金额、货币和支付流程等因素处理符合条件的支付方式的退货。PaymentIntent 是用您在管理平台中配置的支付方式创建的。如不想使用管理平台或想手动指定支付方式,可通过 payment_ method_ types
属性将其列出。
curl https://api.stripe.com/v1/customers \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-X "POST"
curl https://api.stripe.com/v1/ephemeral_keys \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-H "Stripe-Version: 2025-09-30.clover" \
-X "POST" \
-d "customer" = "{{CUSTOMER_ID}}" \
curl https://api.stripe.com/v1/payment_intents \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-X "POST" \
-d "customer" = "{{CUSTOMER_ID}}" \
-d "amount" = 1099 \
-d "currency" = "eur" \
-d "automatic_payment_methods[enabled]" = true \
收集付款详情 显示移动端 Payment Element 前,您的结账页面应:
初始化 您的结账活动的 onCreate
内的一个 PaymentSheet
实例,从而传递一个支付方式来处理结果。
import androidx . compose . runtime . Composable
import androidx . compose . runtime . remember
import com . stripe . android . paymentsheet . PaymentSheet
import com . stripe . android . paymentsheet . PaymentSheetResult
@Composable
fun App ( ) {
val paymentSheet = remember { PaymentSheet . Builder ( :: onPaymentSheetResult ) } . build ( )
}
private fun onPaymentSheetResult ( paymentSheetResult : PaymentSheetResult ) {
}
然后,从您在上一步中创建的端点获取 PaymentIntent 客户端私钥、Ephemeral Key 密钥、Customer ID 以及您的公钥。用 PaymentConfiguration
设置该公钥,然后存储另外几项,供您显示 PaymentSheet 时使用。
import androidx . compose . runtime . Composable
import androidx . compose . runtime . remember
import androidx . compose . runtime . LaunchedEffect
import androidx . compose . runtime . getValue
import androidx . compose . runtime . mutableStateOf
import androidx . compose . runtime . setValue
import androidx . compose . ui . platform . LocalContext
import com . stripe . android . PaymentConfiguration
import com . stripe . android . paymentsheet . PaymentSheet
import com . stripe . android . paymentsheet . PaymentSheetResult
@Composable
fun App ( ) {
val paymentSheet = remember { PaymentSheet . Builder ( :: onPaymentSheetResult ) } . build ( )
val context = LocalContext . current
var customerConfig by remember { mutableStateOf < PaymentSheet . CustomerConfiguration ? > ( null ) }
var paymentIntentClientSecret by remember { mutableStateOf < String ? > ( null ) }
LaunchedEffect ( context ) {
val networkResult = .. .
if ( networkResult . isSuccess ) {
paymentIntentClientSecret = networkResult . paymentIntent
customerConfig = PaymentSheet . CustomerConfiguration (
id = networkResult . customer ,
ephemeralKeySecret = networkResult . ephemeralKey
)
PaymentConfiguration . init ( context , networkResult . publishableKey )
}
}
}
private fun onPaymentSheetResult ( paymentSheetResult : PaymentSheetResult ) {
}
当客户点击您的结账按钮时,调用 presentWithPaymentIntent 来显示支付表单。客户完成付款后,表单将消失,然后 PaymentSheetResult 将调用 PaymentSheetResultCallback 。
import androidx . compose . material . Button
import androidx . compose . material . Text
import androidx . compose . runtime . Composable
import androidx . compose . runtime . LaunchedEffect
import androidx . compose . runtime . getValue
import androidx . compose . runtime . mutableStateOf
import androidx . compose . runtime . remember
import androidx . compose . runtime . setValue
import androidx . compose . ui . platform . LocalContext
import com . stripe . android . PaymentConfiguration
import com . stripe . android . paymentsheet . PaymentSheet
import com . stripe . android . paymentsheet . PaymentSheetResult
@OptIn ( ExperimentalCustomerSessionApi :: class )
@Composable
fun App ( ) {
val paymentSheet = remember { PaymentSheet . Builder ( :: onPaymentSheetResult ) } . build ( )
val context = LocalContext . current
var customerConfig by remember { mutableStateOf < PaymentSheet . CustomerConfiguration ? > ( null ) }
var paymentIntentClientSecret by remember { mutableStateOf < String ? > ( null ) }
LaunchedEffect ( context ) {
val networkResult = .. .
if ( networkResult . isSuccess ) {
paymentIntentClientSecret = networkResult . paymentIntent
customerConfig = PaymentSheet . CustomerConfiguration (
id = networkResult . customer ,
ephemeralKeySecret = networkResult . ephemeralKey
)
PaymentConfiguration . init ( context , networkResult . publishableKey )
}
}
Button (
onClick = {
val currentConfig = customerConfig
val currentClientSecret = paymentIntentClientSecret
if ( currentConfig != null && currentClientSecret != null ) {
presentPaymentSheet ( paymentSheet , currentConfig , currentClientSecret )
}
}
) {
Text ( "Checkout" )
}
}
private fun presentPaymentSheet (
paymentSheet : PaymentSheet ,
customerConfig : PaymentSheet . CustomerConfiguration ,
paymentIntentClientSecret : String
) {
paymentSheet . presentWithPaymentIntent (
paymentIntentClientSecret ,
PaymentSheet . Configuration . Builder ( merchantDisplayName = "My merchant name" )
. customer ( customerConfig )
. allowsDelayedPaymentMethods ( true )
. build ( )
)
}
private fun onPaymentSheetResult ( paymentSheetResult : PaymentSheetResult ) {
when ( paymentSheetResult ) {
is PaymentSheetResult . Canceled -> {
print ( "Canceled" )
}
is PaymentSheetResult . Failed -> {
print ( "Error: ${ paymentSheetResult . error } " )
}
is PaymentSheetResult . Completed -> {
print ( "Completed" )
}
}
}
将 allowsDelayedPaymentMethods
设置为 true,以允许延迟通知型 支付方式,例如美国银行账户。对于这些支付方式,只有当 PaymentSheet
完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式,请告知客户他们的订单已被确认,并且仅在付款成功时履行订单(例如,为他们安排发货)。
测试集成
卡号 场景 如何测试 4242 4242 4242 4242 该卡付款成功,不需要验证。 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 4000 0025 0000 3155 该卡付款时需要验证 。 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 4000 0000 0000 9995 该卡被拒绝,显示拒付代码,例如 insufficient_ funds
。 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。 6205 5000 0000 0000 004 银联卡的长度为 13-19 位。 使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。
有关测试您的集成的更多信息,请参阅测试 部分。
可选 启用 Link
在您的支付方式设置 中启用 Link,以允许客户使用 Link 的一键快速结账按钮安全地保存并重复使用他们的支付信息。
将客户的邮件地址传递到 Mobile Payment Element Link 利用客户的邮件地址对客户进行验证。Stripe 建议预填充尽可能多的信息,以简化结账流程。
要预先填充客户的姓名、邮件地址和电话号码,请在初始化 PaymentSheet. Configuration
时提供包含客户信息的 defaultBillingDetails
。
val configuration = PaymentSheet . Configuration . Builder ( merchantDisplayName = "Example, Inc." )
. defaultBillingDetails (
PaymentSheet . BillingDetails (
name = "Jenny Rosen" ,
email = "jenny.rosen@example.com" ,
phone = "888-888-8888"
)
)
. build ( )
可选 启用 Google Pay
设置您的集成 要使用 Google Pay,先将以下内容添加到您的 AndroidManifest.xml 的 <application>
标签,来启用 Google Pay API:
< application >
...
< meta-data
android: name = " com.google.android.gms.wallet.api.enabled "
android: value = " true " />
</ application >
更多详情,请参见 Google Pay 针对 Android 设备编写的设置 Google Pay API 指南。
添加 Google Pay 要向您的集成添加 Google Pay,初始化 PaymentSheet.Configuration 时,传递您的 Google Pay 环境(生产或测试)下的 PaymentSheet.GooglePayConfiguration 和贵公司的国家/地区代码 。
val googlePayConfiguration = PaymentSheet . GooglePayConfiguration (
environment = PaymentSheet . GooglePayConfiguration . Environment . Test ,
countryCode = "US" ,
currencyCode = "USD"
)
val configuration = PaymentSheet . Configuration . Builder ( merchantDisplayName = "My merchant name" )
. googlePay ( googlePayConfiguration )
. build ( )
测试 Google Pay Google 允许您通过其测试卡套件 进行测试支付。该测试套件支持使用 Stripe 测试卡 。
您可以使用实体 Android 设备测试 Google Pay。确保您的设备位于支持 Google Pay 的国家/地区,并在测试设备上登录到 Google 账户,且 Google Wallet 中保存有真实银行卡数据。
可选 启用银行卡扫描
要启用银行卡扫描支持,将 stripecardscan
添加到您的 app/build.gradle 文件的 dependencies
块中。
apply plugin : 'com.android.application'
android { ... }
dependencies {
implementation 'com.stripe:stripecardscan:21.28.0'
}
可选 启用 ACH 付款
要启用 ACH 借记付款,请将 Financial Connections 作为您的应用的依赖项。
Stripe Android SDK 是开源的,且有完整的文档 。
安装 SDK 时,将 financial-connections
添加到您的 app/build.gradle 文件的 dependencies
块中:
plugins {
id ( "com.android.application" )
}
android { .. . }
dependencies {
implementation ( "com.stripe:financial-connections:21.28.0" )
}
注意 有关最新 SDK 发布及过往版本的详细信息,请查看 GitHub 上的发布 页面。要想在新版本发布时接收通知,请查看仓库的发布情况 。
可选 自定义表单
所有自定义操作均用 PaymentSheet.Configuration 对象来配置。
外观 用 Appearance API 自定义颜色、字体等,使其匹配您的应用的外观样式。
支付方式布局 使用 paymentMethodLayout 配置表单中支付方式的布局。可以水平、垂直显示,也可以让 Stripe 自动优化布局。
PaymentSheet . Configuration . Builder ( "Example, Inc." )
. paymentMethodLayout ( PaymentSheet . PaymentMethodLayout . Automatic )
. build ( )
收集用户地址 用 Address Element 收集客户的本地和国际收货地址或账单地址。
商家显示名称 通过设置 merchantDisplayName 来指定一个向客户显示的商家名称。默认情况下,使用的是您的应用的名称。
PaymentSheet . Configuration . Builder (
merchantDisplayName = "My app, Inc."
) . build ( )
暗色模式 默认情况下,PaymentSheet
自动适应用户的整个系统的外观设置(明暗模式)。可通过在您的应用上设置亮色或暗色模式来更改:
AppCompatDelegate . setDefaultNightMode ( AppCompatDelegate . MODE_NIGHT_YES )
AppCompatDelegate . setDefaultNightMode ( AppCompatDelegate . MODE_NIGHT_NO )
默认账单详情 要为支付表单中收集的账单详情设置默认值,请配置 defaultBillingDetails
属性。paymentSheet
会用您提供的值预先填充其字段。
val address = PaymentSheet . Address ( country = "US" )
val billingDetails = PaymentSheet . BillingDetails (
address = address ,
email = "foo@bar.com"
)
val configuration = PaymentSheet . Configuration . Builder ( merchantDisplayName = "Merchant, Inc." )
. defaultBillingDetails ( billingDetails )
. build ( )
使用 BillingDetailsCollectionConfiguration
指定您希望如何在 PaymentSheet 中收集账单详情。
可以收集客户的姓名、邮件地址、电话号码和地址。
如果希望将默认账单详情关联到 PaymentMethod 对象(即使 UI 中未收集这些字段),请将 billingDetailsCollectionConfiguration. attachDefaultsToPaymentMethod
设置为 true
。
val billingDetails = PaymentSheet . BillingDetails (
email = "foo@bar.com"
)
val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration (
attachDefaultsToPaymentMethod = true ,
name = BillingDetailsCollectionConfiguration . CollectionMode . Always ,
email = BillingDetailsCollectionConfiguration . CollectionMode . Never ,
address = BillingDetailsCollectionConfiguration . AddressCollectionMode . Full ,
)
val configuration = PaymentSheet . Configuration . Builder ( merchantDisplayName = "Merchant, Inc." )
. defaultBillingDetails ( billingDetails )
. billingDetailsCollectionConfiguration ( billingDetailsCollectionConfiguration )
. build ( )
注意 请咨询律师,了解与收集信息有关的法律。仅在需要收集号码来完成交易时,才收集手机号码。
可选 处理用户的退出动作
PaymentSheet
在本地存储一些信息,以记住用户是否在某个应用程序内使用了 Link。要清除 PaymentSheet
的内部状态,在用户登出时调用 PaymentSheet. resetCustomer()
方法。
class MyActivity : Activity {
fun onLogoutButtonClicked ( ) {
PaymentSheet . resetCustomer ( this )
}
}
可选 在您的用户界面完成付款
您可以在出示支付表单时仅收集支付方式详情,然后再在您的应用的用户界面上完成付款。如果您使用的是自定义购买按钮或在收集了付款详情后要求额外的步骤,这会非常有用。
首先,用某个 Builder 方法初始化 PaymentSheet.FlowController ,而非 PaymentSheet
。 class CheckoutActivity : AppCompatActivity ( ) {
private lateinit var flowController : PaymentSheet . FlowController
override fun onCreate ( savedInstanceState : Bundle ? ) {
super . onCreate ( savedInstanceState )
flowController = PaymentSheet . FlowController . Builder (
paymentResultCallback = :: onPaymentSheetResult ,
paymentOptionCallback = :: onPaymentOption ,
) . build ( this )
}
}
然后,用从您的后端获取的 Stripe 对象密钥调用 configureWithPaymentIntent
,并用getPaymentOption() 在回调中更新您的用户界面。这包含一个表示客户当前选择的支付方式的图片和标签。 flowController . configureWithPaymentIntent (
paymentIntentClientSecret = paymentIntentClientSecret ,
configuration = PaymentSheet . Configuration . Builder ( "Example, Inc." )
. customer ( PaymentSheet . CustomerConfiguration (
id = customerId ,
ephemeralKeySecret = ephemeralKeySecret
) )
. build ( )
) { isReady , error ->
if ( isReady ) {
} else {
}
}
然后,调用 presentPaymentOptions 来收集付款详情。客户完成后,表单被丢弃,并调用之前在 create
中传入的 paymentOptionCallback 。实施该方法,用返回的 paymentOption
更新您的 UI。
flowController . presentPaymentOptions ( )
private fun onPaymentOption ( paymentOption : PaymentOption ? ) {
if ( paymentOption != null ) {
paymentMethodButton . text = paymentOption . label
paymentMethodButton . setCompoundDrawablesRelativeWithIntrinsicBounds (
paymentOption . drawableResourceId ,
0 ,
0 ,
0
)
} else {
paymentMethodButton . text = "Select"
paymentMethodButton . setCompoundDrawablesRelativeWithIntrinsicBounds (
null ,
null ,
null ,
null
)
}
}
最后,调用 confirm ,完成付款。客户完成后,表单被丢弃,并调用之前在 create
中创建的 paymentResultCallback 。
flowController . confirmPayment ( )
private fun onPaymentSheetResult (
paymentSheetResult : PaymentSheetResult
) {
when ( paymentSheetResult ) {
is PaymentSheetResult . Canceled -> {
}
is PaymentSheetResult . Failed -> {
}
is PaymentSheetResult . Completed -> {
}
}
}
将 allowsDelayedPaymentMethods
设置为 true,以允许延迟通知型 支付方式,例如美国银行账户。对于这些支付方式,只有当 PaymentSheet
完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式,请告知客户他们的订单已被确认,并且仅在付款成功时履行订单(例如,为他们安排发货)。
可选 启用确认时的 CVC 重新收集流程
以下有关在确认 PaymentIntent 的过程中重新收集已保存卡的 CVC 的说明假定的是您的集成包含以下内容:
在收集支付详情之前创建 PaymentIntent 更新意图创建参数 要在确认付款时重新收集 CVC,请在创建 PaymentIntent 的过程中包含 require_ cvc_ recollection
。
curl https://api.stripe.com/v1/customers \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-X "POST"
curl https://api.stripe.com/v1/ephemeral_keys \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-H "Stripe-Version: 2025-09-30.clover" \
-X "POST" \
-d "customer" = "{{CUSTOMER_ID}}" \
curl https://api.stripe.com/v1/payment_intents \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
-X "POST" \
-d "customer" = "{{CUSTOMER_ID}}" \
-d "amount" = 1099 \
-d "currency" = "eur" \
-d "payment_method_options[card][require_cvc_recollection]" = true \
-d "automatic_payment_methods[enabled]" = true \