调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录
概览升级您的集成
线上付款
概览查找您的用例Use Managed Payments
支付方式
支付接口
支付场景
线下支付
超越支付功能

在应用内付款期间保存付款详情

在移动应用中保存付款过程中的付款详情。

用 Payment Intents API 保存购物时输入的付款详情。有几个用例：

  • 对客户的网上订单扣款并存储支付信息，用于以后的购物。
  • 发起一系列经常性付款中的第一笔付款。
  • 收取押金并存储详情，便于以后收取完整金额。

有卡交易

有卡交易（例如通过 Stripe Terminal 支付）使用不同的流程来保存支付方式。有关详情，请查看 Terminal 文档。

合规

在保存客户的支付详情时，您需要负责遵守所有适用的法律、法规和卡组织规则。如果您想要保存客户的支付方式以供将来使用，则通常会适用于这些要求，例如在结账流程中向他们显示客户的支付方式以供将来购物使用，或者在他们不主动使用您的网站或应用程序时向他们扣款。在您的网站或应用程序中添加条款，说明您计划如何保存支付方式的详细信息，并允许客户选择加入。

保存支付方式后，您只能将它用于条款中包含的特定使用量。要在客户离线时对某种支付方式扣款并将其保存为可供未来购物时选择的选项，请务必收集客户对这一特定用途的明确同意。例如，包含“保存我的支付方式以供未来使用”复选框以收集用户同意书。

要想在他们离线时收款，请确保您的条款中包含以下内容：

  • 客户同意您代其对指定的交易发起一次或一系列付款。
  • 预期的付款时间和频率（例如，收款是计划的分期付款、订阅付款还是计划外充值）。
  • 如何确定付款金额。
  • 如果支付方式是用于支付订阅服务，那即同意您的取消政策。

请务必让客户书面同意这些条款并做好记录。

设置 Stripe
服务器端
客户端

首先，您需要一个 Stripe 账户。立即注册。

服务器端

该集成要求您的服务器上的端点与 Stripe API 通信。用我们的官方库从您的应用程序访问 Stripe API：

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

客户端

Stripe iOS SDK 是开源的，有完整的文档，并且与支持 iOS 13 或更高版本操作系统的应用程序兼容。

要安装 SDK，按这些步骤进行：

  1. 在 Xcode 中，选择文件 > **添加工具包依赖…**并输入 https://github.com/stripe/stripe-ios-spm 作为仓库 URL。
  2. 从我们的发布页面选择最新的版本号。
  3. 将 StripePaymentSheet 产品添加到您的目标应用程序。

注意

有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的发布页面。要想在新版本发布时接收通知，请查看仓库的发布。

启用支付方式

银行卡付款默认启用。查看您的支付方式设置，启用您想支持的更多支付方式。

添加端点
服务器端

注意

要在创建 PaymentIntent 之前显示 PaymentSheet，请参阅收集支付详情后再创建 Intent。

该集成使用三个 Stripe API 对象：

  1. PaymentIntent：Stripe 用它来表示您从客户收款的意图，跟踪您的扣款尝试及整个过程中付款状态的变化情况。

  2. Customer：要为将来的付款设置支付方式，就必须将它绑定到 Customer。当客户在您的公司创建账户时，创建 Customer 对象。如果您的客户以访客身份付款，则可以在付款前创建个 Customer 对象，然后再将它关联到您自己内部的客户账户表示。

  3. Customer Ephemeral Key：Customer 对象的信息属于敏感信息，无法直接从应用中检索。临时密钥授予 SDK 对客户的临时访问权限。

出于安全原因，您的应用无法创建这些对象。相反，在服务器上会添加一个端点，其功能如下：

  1. 检索 Customer，或新建一个。
  2. 为 Customer 创建一个 Ephemeral Key。
  3. 创建 PaymentIntent，设置好 amount、currency 和 customer, setup_future_usage 。您还可以选择包含 automatic_payment_methods 参数。默认情况下，Stripe 会在最新版的 API 中启用其功能。
  4. 将 Payment Intent 的客户端私钥、Ephemeral Key 的 secret 以及 Customer 的 id 和您的公钥返回到您的应用程序。

注意

移动端 Payment Element 仅支持拥有卡和美国银行账户的 setup_future_usage。

在结账过程中显示给客户的支付方式也包含在 PaymentIntent 中。您可以让 Stripe 从管理平台设置中提取支付方式，也可以手动列出它们。无论选择哪种方式，都要知道在 PaymentIntent 中传递的货币会过滤显示给客户的支付方式。例如，如果您在 PaymentIntent 中传递 eur，并且在管理平台中启用了 OXXO，则不会向客户显示 OXXO，因为 OXXO 不支持 eur 支付。

除非您的集成需要基于代码的选项来提供支付方式，否则 Stripe 建议使用自动选项。这是因为 Stripe 会评估货币、支付方式限制和其他参数，以确定支持的支付方式列表。优先显示可提高转化率且与货币和客户所在地最相关的支付方式。

注意

您可以在 CodeSandbox 上分叉并部署此端点的实现方案进行测试。

您可以从管理平台管理支付方式。Stripe 根据交易金额、货币和支付流程等因素处理符合条件的支付方式的退货。PaymentIntent 是用您在管理平台中配置的支付方式创建的。如不想使用管理平台或想手动指定支付方式，可通过 payment_method_types 属性将其列出。

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
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}}" \

# Create a PaymentIntent
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 "setup_future_usage"="off_session" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \

收集付款详情
客户端

要在结账屏幕上显示移动 Payment Element，您必须确保：

  • 显示客户正在购买的产品以及总金额
  • 用 Address Element 从客户那里收集所需的配送信息
  • 添加结账按钮以显示 Stripe 的 UI

在应用的结账屏幕中，从您在上一步创建的端点获取 PaymentIntent 客户端密钥、临时密钥机密、客户 ID 和可发布密钥。使用 StripeAPI.shared 设置可发布密钥并初始化 PaymentSheet。

import UIKit
import StripePaymentSheet

class CheckoutViewController: UIViewController {
  @IBOutlet weak var checkoutButton: UIButton!
  var paymentSheet: PaymentSheet?
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint

  override func viewDidLoad() {
    super.viewDidLoad()

    checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
    checkoutButton.isEnabled = false

    // MARK: Fetch the PaymentIntent client secret, Ephemeral Key secret, Customer ID, and publishable key
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerEphemeralKeySecret = json["ephemeralKey"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, ephemeralKeySecret: customerEphemeralKeySecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true
      self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)

      DispatchQueue.main.async {
        self.checkoutButton.isEnabled = true
      }
    })
    task.resume()
  }

}

当客户点击结账按钮时，调用 present 以显示 PaymentSheet。在客户完成支付后，Stripe 会关闭 PaymentSheet，并使用 PaymentSheetResult 调用完成块。

@objc
func didTapCheckoutButton() {
  // MARK: Start the checkout process
  paymentSheet?.present(from: self) { paymentResult in
    // MARK: Handle the payment result
    switch paymentResult {
    case .completed:
      print("Your order is confirmed")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print("Payment failed: \(error)")
    }
  }
}

如果 PaymentSheetResult 是 .completed，则通知用户（例如，显示订单确认界面）。

将 allowsDelayedPaymentMethods 设置为 true，以允许延迟通知型支付方式，例如美国银行账户。对于这些支付方式，只有当 PaymentSheet 完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式，请告知客户他们的订单已被确认，并且仅在付款成功时履行订单（例如，为他们安排发货）。

设置返回URL
客户端

客户可能会离开您的应用来验证（例如，去 Safari 或他们的网银应用）。若允许他们在验证后自动返回到您的应用，配置一个自定义页面内跳转协议 (URL Scheme)，并设置您的应用程序代理将 URL 转发到 SDK。Stripe 不支持通用链接。

SceneDelegate.swift
Swift
No results
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

此外，将您的 PaymentSheet.Configuration 对象上的 returnURL 设置到您的应用的 URL。

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

处理付款后事件
服务器端

付款完成时，Stripe 会发送一个 payment_intent.succeeded 事件。使用 管理平台 Webhook 工具、或按照 Webhook 指南来接收这些事件并运行操作，例如，向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

侦听这些事件，而不是等待客户端回调。在客户端，客户可能会在执行回调之前关闭浏览器窗口或退出应用程序，并且恶意客户端可能会操纵响应。设置您的集成来侦听异步事件，这样才能用单一集成用用接受不同类型的支付方式。

除了处理 payment_intent.succeeded 事件外，建议在使用 Payment Element 收款时也处理其他的这些事件：

事件描述操作
payment_intent.succeeded客户成功完成付款时发送。向客户发送订单确认通知，并履行他们的订单。
payment_intent.processing当客户成功发起付款但并未完成时发送。当客户发起银行借记时，通常会发送此事件。之后将会出现 payment_intent.succeeded 或 payment_intent.payment_failed 事件。向客户发送订单确认，告知他们的付款正等待处理。对于数字商品，您可能想先履行订单，然后再等付款完成。
payment_intent.payment_failed在客户尝试付款但付款失败时发送。如果一笔付款从 processing 变为 payment_failed，则让客户再尝试一次。

以后对保存的 Payment Method 扣款
服务器端

合规

保存客户的支付详情时，您有责任遵守所有适用的法律、法规和卡组织规则。向您的最终客户呈现之前用过的支付方式以供未来购物使用时，确保您所列出的支付方式已从客户那里收集保存支付方式详情以供将来具体使用的同意书。对于绑定到客户的支付方式，要区分哪些可以哪些不可以作为保存的支付方式供未来购物使用，请使用 allow_redisplay 参数。

准备在会话外对客户扣款时，使用 Customer 和 PaymentMethod ID 创建一个 PaymentIntent。要找到扣款的支付方式，列出与您的客户关联的支付方式。该例中列出了银行卡，但您可以列出任意受支持的 type。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d type=card

当您有 Customer 和 PaymentMethod ID 时，创建一个包含付款金额和货币的 PaymentIntent。设置几个其他参数来进行会话外付款：

  • 将 off_session 设置为 true，以指示客户其在尝试付款时并不在您的结账流程中，并且无法完成合作伙伴（如发卡行、银行或其他支付机构）提出的身份验证请求。如果在您的结账流程中，合作伙伴要求进行验证，Stripe 将使用之前的会话内交易中的客户信息请求豁免。如果不满足豁免条件，PaymentIntent 可能会抛出一个错误。
  • 将 PaymentIntent 的 confirm 属性的值设置为 true，这样就会在创建 PaymentIntent 时立即进行确认。
  • 将 payment_method 设置为 PaymentMethod 的 ID，并将 customer 设置为 Customer 的 ID。
Command Line
curl
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d return_url="https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true

测试整合情况

支付方式场景如何测试
信用卡银行卡设置成功，不要求验证。填写我们的信用卡表单，卡号是 4242 4242 4242 4242，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡该卡在初始设置时需要身份验证，在后续付款时会直接成功。填写我们的信用卡表单，卡号是 4000 0025 0000 3155，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡该卡在初始设置时需要身份验证，在后续付款时也需要身份验证。填写我们的信用卡表单，卡号是 4000 0027 6000 3184，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡设置过程中卡被拒绝了。填写我们的信用卡表单，卡号是 4000 0000 0000 9995，有效期、CVC（银行卡安全码）以及邮编可任意填写。

可选启用 Apple Pay

注意

如果您的结账界面有专门的 Apple Pay 按钮，则按照 Apple Pay 指南中的说明并使用 ApplePayContext 从您的 Apple Pay 按钮收款。您可以用 PaymentSheet 来处理其他支付方式类型。

注册 Apple Merchant ID

可通过在 Apple 开发人员网站注册新的标识符来获取 Apple 商家 ID。

在表单中填写描述和标识符。描述内容仅供您自己记录之用，之后可随时更改。Stripe 建议用您的应用的名称作为标识符（例如，merchant.com.{{YOUR_APP_NAME}}）。

创建新的 Apple Pay 证书

为您的应用创建证书，以加密支付数据。

转到管理平台中的 iOS 证书设置，点击添加新应用程序，然后按照说明进行操作。

下载证书签名请求 (CSR) 文件，来从 Apple 获取安全证书，以便使用 Apple Pay。

必须用一个 CSR 文件发布具体的一个证书。如果您切换您的 Apple Merchant ID，则必须前往管理平台的 iOS 证书设置中获取一个新的 CSR 和证书。

集成 Xcode

将 Apple Pay 功能添加到您的应用程序。在 Xcode 中，打开您的项目设置，点击签名和功能选项卡，然后添加 Apple Pay 功能。此时，系统可能会提示您登入您的开发人员账户。选择您之前创建的商家 ID，您的应用程序就可以接受 Apple Pay 了。

在 Xcode 中启用 Apple Pay 功能

添加 Apple Pay

要将 Apple Pay 添加到 PaymentSheet，用您的 Apple 商家 ID 和国家/地区代码初始化 PaymentSheet.Configuration 之后设置 applePay。

var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
  merchantId: "merchant.com.your_app_name",
  merchantCountryCode: "US"
)

订单跟踪

要在 iOS 16 或更高版本中添加订单跟踪信息，请在您的 PaymentSheet.ApplePayConfiguration.Handlers 中配置一个 authorizationResultHandler。Stripe 会在支付完成后调用您的实施的程序，但该操作在 iOS 关闭 Apple Pay 表单之前进行。

在您的 authorizationResultHandler 部署环境中，从您的服务器获取已完成订单的详情。将详情添加到提供的 PKPaymentAuthorizationResult 并调用提供的完成处理程序。

要了解有关订单跟踪的更多信息，请参阅 Apple 钱包订单文档。

let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    authorizationResultHandler: { result, completion in
        // Fetch the order details from your service
        MyAPIClient.shared.fetchOrderDetails(orderID: orderID) { myOrderDetails
            result.orderDetails = PKPaymentOrderDetails(
                orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
                orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
                webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
                authenticationToken: myOrderDetails.authenticationToken) // "abc123"
            // Call the completion block on the main queue with your modified PKPaymentAuthorizationResult
            completion(result)
        }
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                               merchantCountryCode: "US",
                               customHandlers: customHandlers)

可选启用银行卡扫描

要启用银行卡扫描功能，在您的应用的 Info.plist 中设置 NSCameraUsageDescription（隐私 - 摄像头使用说明），然后提供使用摄像头的原因（例如，“要扫描银行卡”）。iOS 13 或以上版本的设备支持银行卡扫描。

可选自定义表单

所有自定义操作均通过 PaymentSheet.Configuration 对象来配置。

外观

用 Appearance API 自定义颜色、字体等，使其匹配您的应用程序的外观样式。

支付方式布局

使用 paymentMethodLayout 配置表单中支付方式的布局。可以水平、垂直显示，也可以让 Stripe 自动优化布局。

var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic

收集用户地址

用 Address Element 收集客户的本地和国际收货地址或账单地址。

商家显示名称

通过设置 merchantDisplayName 来指定一个向客户显示的商家名称。默认情况下，使用的是您的应用的名称。

var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."

暗色模式

PaymentSheet 自动适应用户的系统范围内的外观设置（明暗模式）。如果您的应用不支持暗色模式，可将 style 设置到 alwaysLight 或 alwaysDark 模式。

var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight

默认账单详情

要为支付表单中收集的账单详情设置默认值，请配置 defaultBillingDetails 属性。paymentSheet 会用您提供的值预先填充其字段。

var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"

收集账单详情

用 billingDetailsCollectionConfiguration 来指定您希望如何在支付表单中收集账单详情。

可以收集客户的姓名、邮件地址、电话号码和地址。

如果您只想通过支付方式获得所需的账单详情，请将 billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod 设置为 true。在这种情况下，PaymentSheet.Configuration.defaultBillingDetails 被设置为支付方式的 billing details。

如果您希望收集支付方式非必需的额外账单详情，请将 billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod 设置为 false。在这种情况下，通过 PaymentSheet 收集的账单详情被设置为支付方式的账单详情。

var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true

注意

请咨询律师，了解与收集信息有关的法律。仅在需要收集号码来完成交易时，才收集手机号码。

可选在您的用户界面完成付款

您可以在出示支付表单时仅收集支付方式详情，然后再在您的应用的用户界面上调用 confirm 方法来完成付款。如果您使用自定义购买按钮，或在收集了付款详情后需要额外的步骤，这会非常有用。

在您的应用程序的用户界面内完成付款

以下步骤将引导您在您的应用程序的用户界面内完成付款。前往 GitHub 查看我们的示例集成。

  1. 首先，初始化 PaymentSheet.FlowController，而非 PaymentSheet，并用它的 paymentOption 属性更新您的用户界面。该属性包含表示客户最初选择的默认支付方式的图片和标签。
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Update your UI using paymentSheetFlowController.paymentOption
  }
}
  1. 然后，调用 presentPaymentOptions 来收集付款详情。完成后，用 paymentOption 属性再次更新您的用户界面。
paymentSheetFlowController.presentPaymentOptions(from: self) {
  // Update your UI using paymentSheetFlowController.paymentOption
}
  1. 最后，调用 confirm。
paymentSheetFlowController.confirm(from: self) { paymentResult in
  // MARK: Handle the payment result
  switch paymentResult {
  case .completed:
    print("Payment complete!")
  case .canceled:
    print("Canceled!")
  case .failed(let error):
    print(error)
  }
}

将 allowsDelayedPaymentMethods 设置为 true，以允许延迟通知型支付方式，例如美国银行账户。对于这些支付方式，只有当 PaymentSheet 完成后才能知道最终的付款状态是成功还是失败。如果您支持这些类型的支付方式，请告知客户他们的订单已被确认，并且仅在付款成功时履行订单（例如，为他们安排发货）。

此页面的内容有帮助吗？
是否