错误处理
捕获并响应卡组织拒付、无效数据、卡组织问题等。
Stripe 提供很多种错误。可能会反映外部事件(如付款被拒绝和卡组织中断),也可能会反映代码问题(如 API 调用无效)。
处理错误时,可以使用下表中的部分或全部方法。无论用哪个方法,您都可以遵从我们为各类错误推荐的响应方式。
方法 | 目的 | 需要时 |
---|---|---|
使用错误值 | API 调用不能继续时恢复 | 总是 |
监测 Webhook | 从 Stripe 对通知做出反应 | 有时候 |
获取存储的故障相关信息 | 调查过往问题并支持其他方法 | 有时候 |
使用错误值
Stripe Go 库中的 API 调用会同时返回一个结果值和一个错误值。使用多个任务捕获两个。如果错误值不是 nil
,则说明有非直接的问题妨碍了 API 调用继续。
如果错误值与 Stripe 相关,则可以将它转换为一个 stripe.
对象,它的字段会对问题进行描述。用 Type 字段选择一个响应方式。某些情况下,您可以用额外的信息强制将 Err
属性变成更为具体的错误类型。
设置完异常处理措施后,使用包括测试卡在内的多种数据进行测试,来模拟不同的支付结果。
监测 Webhook
Stripe 会用 Webhook 通知您很多中问题。包括那些在 API 调用后不会立即发生的问题。例如:
- 您输掉了一个争议。
- 经常性付款在成功几个月后仍可能会失败。
- 您的前端确认一笔付款,然后在发现付款失败之前就会离线。(后端仍会收到 Webhook 通知,即使不是发出 API 调用的那一个。)
您不需要处理每个 Webhook 事件类型。事实上,有些集成一个都不会处理。
在您的 Webhook 处理程序中,从 Webhook 构建器的基本步骤开始:获取一个事件对象,用事件类型查看到底发生了什么情况。然后,如果事件类型指示有错误,执行以下步骤:
- 通过从
event.
解组数据来获取受影响的对象。Data. Raw - 使用存储的受影响对象信息来获取上下文,包括错误对象。
- 用它的类型来选择一个响应方式。
要测试您的集成对 Webhook 事件的响应情况,您可以在本地触发 Webhook 事件。完成此链接的设置步骤后,触发一个失败的付款,看引发的错误消息是什么。
stripe trigger payment_intent.payment_failed
A payment error occurred: Your card was declined.
获取存储的故障相关信息
很多对象存储着有关故障的信息。这就是说,如果已经发生了错误,则您可以检索对象进行检查,了解更多信息。很多情况下,存储的信息采用的是错误对象的形式,您可以用它的类型来选择一个响应方式。
例如:
- 检索特定的支付意图。
- 通过确定 last_payment_error 是否为空,检查它是否遇到了支付错误。
- 如果为空,则记录错误,包括其类型和受影响的对象。
这是一些存储了故障信息的常见对象。
对象 | 属性 | 值 |
---|---|---|
付款意图 | last_ | 错误对象 |
设置意图 | last_ | 错误对象 |
账单 | last_ | 错误对象 |
设置尝试 | setup_ | 错误对象 |
提现 | failure_ | 提现失败代码 |
退款 | failure_ | 退款失败代码 |
要测试使用了存储的故障信息的代码,通常需要模拟失败的交易。一般可以用测试卡或测试银行账号进行。例如:
错误类型及解决方案
在 Stripe Go 库中,每个错误对象都有一个 Type
属性。用各类别的文档,查看相应的解决建议。
名称 | 类型 | 描述 |
---|---|---|
支付错误 | 支付过程中发生了错误,涉及这些情况中的某一种: | |
无效请求错误 | 您采用的 API 调用方式目前是无效的。这可能包括: | |
API 错误 | Stripe 这一端出错了。(这种情况比较少见。) | |
幂等性错误 | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
银行卡错误
支付错误(因历史原因,有时被称为“银行卡错误”)涵盖了很多常见的问题。它们分为三类:
To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Users on API version 2022-08-01 or older:
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
您可以用测试卡模拟一些常见类型的支付错误。可参考这些列表中的选项:
下面的测试代码演示了一些可能的情况。
因疑似欺诈被阻止
类型 |
|
代码 |
|
代码 |
|
问题 | Stripe 的欺诈预防系统 Radar 阻止了付款 |
解决方案 | 当您的集成正确运行的情况下可能会发生这种错误。捕获它,然后提示客户换一个支付方式。 要减少阻止的合法付款,可尝试这些操作:
Radar 风控团队版客户还有以下额外的选项:
You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation. |
被发卡行拒绝
类型 |
|
代码 |
|
问题 | 发卡行拒绝了付款。 |
解决方案 | This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action may be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code. 您还可以:
Test how your integration handles declines with test cards that simulate successful and declined payments. |
其他支付错误
类型 |
|
问题 | 发生了另一个支付错误。 |
解决方案 | This error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code. |
无效请求错误
无效请求错误覆盖了一系列情况。最常见的一个是当 API 请求有无效的参数或您的集成的当前状态不允许时。可以用错误代码 (stripeErr.
) 并查阅错误代码文档来寻找解决方案。有些错误代码需特别对待:
速率限制错误
类型 |
|
代码 | stripeErr. |
问题 | 您短时间内进行的 API 调用太多。 |
解决方案 |
|
验证错误
类型 |
|
代码 | stripeErr. |
问题 | Stripe 无法用您提供的信息对您进行验证。 |
解决方案 |
|
无效参数或状态
类型 |
|
代码 | stripeErr. |
问题 | 您的 API 调用是用错误的参数、在错误的状态下,或以一种无效的方式发起的。 |
解决方案 | 多数情况下,问题是关于请求本身的。要么是它的参数无效,要么它不能在您的集成的当前状态下执行。
|
API 错误
类型 |
|
问题 | Stripe 这一端出错了。(这种情况比较少见。) |
解决方案 | 将 API 调用的结果视为不确定的。也就是说,不要假定它成功了或失败了。 依靠 Webhook 来获取结果信息。只要有可能,在我们解决掉一个问题时,Stripe 就会为我们创建的任何新对象触发 Webhook。 To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors. |
幂等性错误
类型 |
|
问题 | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
解决方案 |
|