调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录

错误处理

捕获并响应卡组织拒付、无效数据、卡组织问题等。

复制页面

Stripe 提供很多种错误。可能会反映外部事件（如付款被拒绝和卡组织中断），也可能会反映代码问题（如 API 调用无效）。

处理错误时，可以使用下表中的部分或全部方法。无论用哪个方法，您都可以遵从我们为各类错误推荐的响应方式。

方法目的需要时
捕获异常API 调用不能继续时恢复总是
监测 Webhook从 Stripe 对通知做出反应有时候
获取存储的故障相关信息调查过往问题并支持其他方法有时候

捕获异常

如果立即发生问题，妨碍某个 API 调用继续，则 Stripe Ruby 库会引发一个异常。最佳做法是捕获并处理异常。

要捕获某个异常，使用 Ruby 的 rescue 关键词。捕获 Stripe::StripeError 或它的子类，以仅处理特定的 Stripe 异常。每个子类代表一种不同的异常。捕获某个异常时，您可以用它的类型来选择一个响应方式。

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

设置完异常处理措施后，使用包括测试卡在内的多种数据进行测试，来模拟不同的支付结果。

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

监测 Webhook

Stripe 会用 Webhook 通知您很多中问题。包括那些在 API 调用后不会立即发生的问题。例如：

  • 您输掉了一个争议。
  • 经常性付款在成功几个月后仍可能会失败。
  • 您的前端确认一笔付款，然后在发现付款失败之前就会离线。（后端仍会收到 Webhook 通知，即使不是发出 API 调用的那一个。）

您不需要处理每个 Webhook 事件类型。事实上，有些集成一个都不会处理。

在您的 Webhook 处理程序中，从 Webhook 构建器的基本步骤开始：获取一个事件对象，用事件类型查看到底发生了什么情况。然后，如果事件类型指示有错误，执行以下步骤：

  1. 访问 event.data.object，以检索受影响的对象。
  2. 使用存储的受影响对象信息来获取上下文，包括错误对象。
  3. 用它的类型来选择一个响应方式。
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

要测试您的集成对 Webhook 事件的响应情况，您可以在本地触发 Webhook 事件。完成此链接的设置步骤后，触发一个失败的付款，看引发的错误消息是什么。

Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.

获取存储的故障相关信息

很多对象存储着有关故障的信息。这就是说，如果已经发生了错误，则您可以检索对象进行检查，了解更多信息。很多情况下，存储的信息采用的是错误对象的形式，您可以用它的类型来选择一个响应方式。

例如：

  1. 检索特定的支付意图。
  2. 通过确定 last_payment_error 是否为空，检查它是否遇到了支付错误。
  3. 如果为空，则记录错误，包括其类型和受影响的对象。
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

这是一些存储了故障信息的常见对象。

对象属性值
付款意图last_payment_error错误对象
设置意图last_setup_error错误对象
账单last_finalization_error错误对象
设置尝试setup_error错误对象
提现failure_code提现失败代码
退款failure_reason退款失败代码

要测试使用了存储的故障信息的代码，通常需要模拟失败的交易。一般可以用测试卡或测试银行账号进行。例如：

错误类型及解决方案

在 Stripe Ruby 库中，错误对象属于 stripe.error.StripeError 及其子类别。用各类别的文档，查看相应的解决建议。

名称

等级

描述
支付错误

Stripe::CardError

支付过程中发生了错误，涉及这些情况中的某一种：
无效请求错误

Stripe::InvalidRequestError

您的 API 调用是用错误的参数、在错误的状态下，或以一种无效的方式发起的。

连接错误

Stripe::APIConnectionError

您的服务器与 Stripe 之间发生了网络问题。
API 错误

Stripe::APIError

Stripe 这一端出错了。（这种情况比较少见。）
验证错误

Stripe::AuthenticationError

Stripe 无法用您提供的信息对您进行验证。
幂等性错误

Stripe::IdempotencyError

You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
权限错误

Stripe::PermissionError

该请求中使用的 API 密钥没有必需的权限。
速率限制错误

Stripe::RateLimitError

您短时间内进行的 API 调用太多。
签名验证错误

Stripe::SignatureVerificationError

You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

支付错误

支付错误（因历史原因，有时被称为“银行卡错误”）涵盖了很多常见的问题。它们分为三类：

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

您可以用测试卡模拟一些常见类型的支付错误。可参考这些列表中的选项：

下面的测试代码演示了一些可能的情况。

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

付款因疑似欺诈被阻止

类型

Stripe::CardError

代码
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
代码

e.error.payment_intent.charges.data[0].outcome.type == 'blocked'

问题Stripe 的欺诈预防系统 Radar 阻止了付款

解决方案

当您的集成正确运行的情况下可能会发生这种错误。捕获它，然后提示客户换一个支付方式。

要减少阻止的合法付款，可尝试这些操作：

Radar 风控团队版客户还有以下额外的选项：

  • 要豁免特定的付款，将它添加到您的允许列表。Radar 风控团队版
  • To change your risk tolerance, adjust your risk settings. Radar 风控团队版
  • To change the criteria for blocking a payment, use custom rules. 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.

付款被发卡行拒绝

类型

Stripe::CardError

代码

e.error.code == "card_declined"

问题发卡行拒绝了付款。

解决方案

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might 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.

其他支付错误

类型

Stripe::CardError

问题发生了另一个支付错误。
解决方案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.

无效请求错误

类型

Stripe::InvalidRequestError

问题您的 API 调用是用错误的参数、在错误的状态下，或以一种无效的方式发起的。
解决方案多数情况下，问题是关于请求本身的。要么是它的参数无效，要么它不能在您的集成的当前状态下执行。
  • Consult the error code documentation for details on the problem.
  • 为方便操作，您可以按照 的链接来访问错误代码文档。
  • 如果错误中涉及到具体的参数，则用 来确定具体是哪一个。

连接错误

类型

Stripe::APIConnectionError

问题您的服务器与 Stripe 之间发生了网络问题。

解决方案

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

要知道是否成功，您可以：

  • 从 Stripe 检索相关对象并检查其状态。
  • 侦听操作成功或失败的 Webhook 通知。

To help recover from connection errors, you can:

  • When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
  • 开启自动重试。然后，Stripe 为您生成幂等性密钥，并在安全的情况下为您重复请求。

该错误可能会掩盖其他错误。可能会发生这种情况，即解决掉连接错误后，会出现其他一些错误。检查所有方案中的错误，与您在原始请求中的操作一样。

API 错误

类型

Stripe::APIError

问题Stripe 这一端出错了。（这种情况比较少见。）

解决方案

将 API 调用的结果视为不确定的。也就是说，不要假定它成功了或失败了。

依靠 Webhook 来获取结果信息。只要有可能，在我们解决掉一个问题时，Stripe 就会为我们创建的任何新对象触发 Webhook。

To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

验证错误

类型

Stripe::AuthenticationError

问题Stripe 无法用您提供的信息对您进行验证。
解决方案

幂等性错误

类型

Stripe::IdempotencyError

问题You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
解决方案
  • 使用幂等性密钥时，只有在 API 调用完全相同时才能重用。
  • 使用 255 字符限制的幂等性密钥。

权限错误

类型

Stripe::PermissionError

问题The API key used for this request doesn’t have the necessary permissions.
解决方案
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

速率限制错误

类型

Stripe::RateLimitError

问题您短时间内进行的 API 调用太多。
解决方案
  • 如果单个 API 调用触发了此错误，则等待一会，然后重试。
  • To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
  • 如果您预计流量会激增，因而想要申请提高速率限制的话，请事先联系支持。

签名验证错误

类型

Stripe::SignatureVerificationError

问题You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

解决方案

当您的集成正确运行的情况下可能会发生这种错误。如果您使用的是 Webhook 签名验证，则当有第三方尝试给您发送虚假或恶意的 Webhook 时，就会发生验证失败问题，进而引发此错误。捕获它，并用 400 Bad Request 状态码响应。

If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.

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