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

履行订单

了解如何通过 Checkout Sessions API 履行收到的付款。

复制页面

当您收到通过 Checkout Sessions API（包括 Payment Links）进行的付款时，您可能需要采取措施，将所支付的款项提供给您的客户。例如，您可能需要授予他们使用服务的权限，或者您可能需要向他们运送实物商品。这个过程称为履行，有两种方法可以处理这个过程：

  • 手动进行：您可以使用 Stripe 提供给您的信息手动履行订单。例如，您可以监控管理平台，查看付款通知电子邮件，或者查看报告后再履行订单。
  • 自动进行：您可以建立一个自动化履行系统。推荐

第一种方式适用于小批量或实验性业务，但在大多数情况下，我们建议自动履行。本指南的其余部分将向您展示如何构建自动履行系统。

自动履行

下面所列的自动履行系统结合使用 webhooks 和重定向到您的网站来触发履行。您必须使用 Webhook 来确保每笔付款都得到履行，重定向可让您的客户在付款后立即访问服务或履行详情。

注意

Payment Links 使用 Checkout，因此除非另有说明，否则以下所有信息均适用于 Payment Links 和 Checkout。

创建履行功能
服务器端

在您的服务器上创建一个功能来履行成功的付款。Webhook 会触发该函数，当客户在完成结账后被发送到您的网站时调用该函数。本指南将此函数称为 fulfill_checkout，但您可以根据需要命名函数。

您的 fulfill_checkout 函数必须：

  1. 正确处理用同一 Checkout Session ID 被多次调用的操作。
  2. 接受 Checkout Session ID 作为参数。
  3. 使用 line_items 属性 expanded 从 API 中检索 Checkout Session。
  4. 检查 payment_status 属性，确定它是否需要履行。
  5. 执行行项目的履约。
  6. 记录所提供的 Checkout Session 的履约状态。

用下面的代码作为您的 fulfill_checkout 函数的起点。TODO注释表示您必须实现的任何功能。

注意

下面的代码片段可能会根据选择的语言将 fulfill_checkout 函数命名为 fulfillCheckout 或 FulfillCheckout，但它们都表示相同的函数。

def fulfill_checkout(session_id)
  # Set your secret key. Remember to switch to your live secret key in production.
  # See your keys here: https://dashboard.stripe.com/apikeys
  Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


  puts "Fullfilling Checkout Session #{session_id}"

  # TODO: Make this function safe to run multiple times,
  # even concurrently, with the same session ID

  # TODO: Make sure fulfillment hasn't already been
  # performed for this Checkout Session

  # Retrieve the Checkout Session from the API with line_items expanded
  checkout_session = Stripe::Checkout::Session.retrieve({
    id: session_id,
    expand: ['line_items'],
  })

  # Check the Checkout Session's payment_status property
  # to determine if fulfillment should be performed
  if checkout_session.payment_status != 'unpaid'
    # TODO: Perform fulfillment of the line items

    # TODO: Record/save fulfillment status for this
    # Checkout Session
  end
end

注意

如果 Checkout Session 有很多行项目，则结合使用 API for Checkout line items 的 auto-pagination 来检索所有行项目。

根据您接受的支付方式和业务需求，您可能希望让您的 fulfill_checkout 函数执行以下操作：

  • 提供服务访问权限。
  • 触发发货操作。
  • 在自己的数据库中保存一份付款详情和行项目。
  • 如果您没有启用 Stripe 的收据，则向客户发送自定义收据邮件。
  • 如果您允许客户在 Checkout 中调整数量，则核对行项目和购买数量。
  • 更新库存或库存记录。

创建支付事件处理程序
服务器端

要触发履约操作，创建一个 Webhook 事件处理程序来侦听付款事件并触发您的 fulfill_checkout 函数。

当有人向您付款时，它会创建一个 checkout.session.completed 事件。在您的服务器上设置一个端点来接受、处理和确认接收这些事件。

即时型支付方式与延迟型支付方式

某些支付方式不是即时型的，例如 ACH 直接借记和其他银行转账。这意味着，当结账完成时，资金不会立即到账。延迟型支付方式稍后付款成功时生成一个 checkout.session.async_payment_succeeded 事件。对象的状态为“处理中”，直至付款状态成功或失败。

注意

以下代码中显示的 Webhook 私钥 (whsec_...) 要么来自 Stripe CLI，要么来自您的 Webhook 端点。您可以用 Stripe CLI 进行本地测试，当处理程序在服务器上运行时，Stripe 会用 Webhook 端点向您的处理程序发送事件。更多详情见下一节。

require 'sinatra'

# Use the secret provided by Stripe CLI for local testing
# or your webhook endpoint's secret.
endpoint_secret = 'whsec_...'

post '/webhook' do
  event = nil

  # Verify webhook signature and extract the event
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    payload = request.body.read
    event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
  rescue JSON::ParserError => e
    # Invalid payload
    return status 400
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    return status 400
  end

  if event['type'] == 'checkout.session.completed' ||
  event['type'] == 'checkout.session.async_payment_succeeded'
    fulfill_checkout(event['data']['object']['id'])
  end

  status 200
end

您可能还想侦听和处理 checkout.session.async_payment_failed 事件。例如，当延迟付款失败时，您可以向客户发送电子邮件。

在本地测试您的事件处理程序

开发并测试 Webhook 事件处理程序的最快方式是使用 Stripe CLI。如果您没有 Stripe CLI，请按照安装指南开始使用。

安装 Stripe CLI 后，您可以在本地测试您的事件处理程序。运行您的服务器（例如，在 localhost:4242上），然后运行 stripe listen 命令，让 Stripe CLI 将事件转发到您的本地服务器：

Command Line
stripe listen --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)

将 Webhook 私钥 (whsec_...) 添加到您的事件处理代码中，然后以客户身份通过 Checkout 来测试履约情况：

  • 按结账按钮，带您前往 Checkout，或访问您的 Payment Link
  • 在 Checkout 中提供以下测试数据：
    • 输入 4242 4242 4242 4242 作为卡号
    • 输入一个任意的未来日期作为银行卡有效期
    • 输入任意 3 位数作为 CVC
    • 输入任意账单邮编 (90210)
  • 按下支付按钮

在付款完成后，请验证以下内容：

  • 在运行 stripe listen 的命令行中，它会显示一个转发到您的本地服务器的 checkout.session.completed 事件。
  • 您的服务器日志显示的是 fulfill_checkout 函数的预期输出。

创建 Webhook 端点

在本地测试后，在您的服务器上启动并运行您的 Webhook 事件处理程序。然后，创建一个 Webhook 端点，向您的服务器发送 checkout.session.completed 事件，然后再次测试结账流程。

配置登录页 URL
推荐

将 Checkout 配置为在客户完成结账后将客户引导到您网站上的某个页面。在您的页面的 URL 中包含 {CHECKOUT_SESSION_ID} 占位符，当您的客户从 Checkout 重定向时，它会替换为 Checkout 会话 ID。

托管式 Checkout

对于默认 ui_mode 设为 hosted 的 Checkout Sessions，需要设置 success_url。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

注意

如果您设置了 Webhook 端点来侦听 checkout.session.completed 事件并设置了 success_url，则 Checkout 最多会等待 10 秒钟，让您的服务器响应 Webhook 事件的发送，然后再重定向您的客户。如果使用这种方法，请确保您的服务器能够尽快响应 checkout.session.completed 事件。

在组织账户中注册的 Webhook 端点不支持此行为。在重定向 Checkout 客户时，Stripe 不会等待侦听 checkout.sessions.completed 的组织 Webhook 端点做出响应。

Payment Links

对于用 API 创建的 Payment Links，设置 after_completion.redirect.url。

Command Line
curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d "after_completion[type]"=redirect \
  --data-urlencode "after_completion[redirect][url]"="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

对于您在管理平台中创建的 Payment Links：

  1. 转到付款后选项卡。
  2. 选择不显示确认页面。
  3. 提供包含 {CHECKOUT_SESSION_ID} 占位符的登录页面的 URL（例如 https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}）

在登录页上触发履行操作
推荐

需要侦听 Webhooks以确保您始终触发每笔付款的履行操作，但 Webhook 有时会有延迟。要优化您的支付流程并保证在客户到场时能立即履行订单，也可从您的登录页面触发履行。

使用您在上一步中指定的 URL 中的 Checkout Session ID 执行以下操作：

  1. 当您的服务器收到 Checkout 登录页面的请求时，从 URL 中提取 Checkout Session ID。
  2. 使用提供的 ID 运行您的 fulfill_checkout 函数。
  3. 在履行尝试完成后呈现页面。

呈现登录页时，可以显示以下内容：

  • 履行过程详情。
  • 关于客户现在可以访问的服务的链接或信息。
  • 实物商品的运输或物流详情。

Webhook 为必填项

您不能仅依靠从 Checkout 登录页面触发履约操作，因为无法保证您的客户会访问该页面。例如，有人可以在 Checkout 中成功付款，但在您的登录页面加载之前会断开互联网连接。

设置 Webhook 事件处理程序，这样 Stripe 就可以直接向您的服务器发送支付事件，完全绕过客户端。Webhook 提供了确认您何时收款的最可靠方式。如果 Webhook 事件传送失败，Stripe 会重试多次。

此页面的内容有帮助吗？
是否
需要帮助？联系支持。
加入我们的早期使用计划。
查看我们的更改日志。
有问题？联系销售。
LLM? Read llms.txt.
Powered by Markdoc