通过 Checkout 履行订单
集成了 Stripe Checkout 或创建了 Stripe Payment Link 以将您的客户引到支付表单后,您需要接收通知,以在其付款后履行订单。
本指南中,您将学会如何:
- 客户支付后接收事件通知。
- 处理事件。
- 用 Stripe CLI 快速测试您的新事件处理程序。
- 可以选择性地处理额外的支付方式。
- 在生产中开启您的事件处理程序。
创建事件处理程序服务器端
在这个部分,您将创建一个小的事件处理程序,以便 Stripe 在客户完成结账时给您发送一个 checkout.session.completed
事件。
首先,为您的事件处理程序创建一个新的路径。先打印收到的事件。在下一步验证事件提交是否有效。
测试
运行您的服务器(例如,在 localhost:4242
上)。然后,设置 Stripe CLI,将事件转发到您的本地服务器,在本地测试您的事件处理程序。
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
然后,作为客户走一遍 Checkout:
- 点击结账按钮(您可能在收款指南中有此设置)
- 用测试数据填写您的支付表单
- 输入
4242 4242 4242 4242
作为卡号 - 输入一个任意的未来日期作为银行卡有效期
- 输入任意 3 位数作为 CVC
- 输入任意账单邮编 (
90210
)
- 输入
- 点击支付按钮
您应该会看到:
stripe listen
输出中有checkout.session.completed
- 一个来自服务器事件日志的打印表,上有
checkout.session.completed
事件
现在,您已验证了事件的提交操作,可通过一些手段添加一层安全性,确保事件仅来自 Stripe。
验证来自 Stripe 的事件
任何人都可以向您的事件处理程序发布数据。处理某个事件前,始终要先验证它是来自 Stripe,然后再信任它。Stripe 官方库中内置有 Webhook 事件验证支持,需要用它来更新您的事件处理程序:
测试
走一遍上一步的测试流程。应该仍会看到成功打印出 checkout.session.completed
事件。
然后,用一个未签名的请求触碰这个端点:
curl -X POST \ -H "Content-Type: application/json" \ --data '{ "fake": "unsigned request" }' \ -is http://localhost:4242/webhook HTTP/1.1 400 Bad Request ... more headers
您应该会收到一个 400 Bad Request
错误码,因为您尝试向您的端点发送的是一个未签名的请求。
现在,事件处理程序的基本设置已完成,可继续至履行订单步骤。
履行订单服务器端
处理 checkout.session.completed
事件,履行订单。根据您接受的支付方式(例如,银行卡或移动钱包),您可能需要处理一些额外的事件。该事件包含 Checkout Session 对象,其中包含客户及其付款详情。处理该事件时,您还可以考虑:
- 在自己的数据库中保存一份订单副本。
- 给客户发送收据邮件。
- 如果使用了
line_item.adjustable_quantity
,则核对行项目及客户购买数量。如果 Checkout Session 有很多行项目,则可以用 line_items 对它们进行分页。
处理重定向行为
您可以将 Checkout 配置为在收到 Webhook 事件后重定向您的客户。Checkout 处理这些由 Webhook 触发的重定向的方式略有不同,这取决于您使用的是嵌入式表单还是 Stripe 托管页面。
Stripe 托管页面 | 在您确认收到事件后,您的 Webhook 端点会将客户重定向到 success_url 。如果您的端点掉线或不能正确确认事件,您的处理器会在付款成功 10 秒后将客户重定向到 success_url 。 |
嵌入式表单 | 您的 Webhook 端点会立即将您的客户重定向到 return_url 。您不需要确认您收到了该事件。 |
测试
确保 stripe listen
仍在运行。以测试用户身份走一遍 Checkout,和前面的步骤完全一样。您的事件处理程序应该会收到一个 checkout.session.completed
事件,并且您应该已经成功处理了它。
处理延迟通知型支付方式服务器端
收到通过延迟通知型支付方式进行的付款时,资金不会立即到账。资金处理可能需要好几天,因此您应该延迟履行订单,直至资金到达您的账户。付款成功后,相关的 PaymentIntent 的状态将从 processing
变为 succeeded
。
您需要处理以下 Checkout 事件:
事件名称 | 描述 | 后续步骤 |
---|---|---|
checkout.session.completed | 客户通过提交 Checkout 表单成功授权了借记付款。 | 等待付款成功或失败。 |
checkout.session.async_payment_succeeded | 客户付款成功。 | 交付购买的商品或服务。 |
checkout.session.async_payment_failed | 付款被拒绝,或因其他原因未成功。 | 通过邮件联系客户,让其重新下单。 |
这些事件都会包含 Checkout Session 对象。
更新您的事件处理程序,以履行订单:
测试
确保 stripe listen
仍在运行。以测试用户身份走一遍 Checkout,和之前步骤一样。您的事件处理程序应该会收到一个 checkout.session.completed
事件,并且您应该已经成功处理了它。
这些步骤都已完成,可随时将其投入生产。
投入生产
将您的事件处理器部署到生产后,您需要向 Stripe 注册您的真实 URL。按照指南注册一个 Webhook。