コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要
バージョン管理
API バージョンのアップグレード
開発者向けのツール
Stripe 健全性アラートBuild with LLMsVisual Studio Code をご利用の場合ファイルのアップロード
セキュリティ
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 コールの直後に発生する問題以外も含まれます。以下に例を紹介します。

  • 不審請求の申請についての主張が認められなかった。
  • 継続支払いが数か月成功した後に失敗した。
  • フロントエンドが支払いを確定したが、支払いの失敗を検出する前にオフラインになった (バックエンドは、API コールを行っていなくても、Webhook 通知を受信します)。

すべての Webhook イベントタイプを処理する必要はありません。実際、何も処理しない実装もあります。

Webhook ハンドラで、Webhook ビルダーの基本的なステップから開始します。Event オブジェクトを取得し、イベントタイプを使用して何が起こったかを調べます。次に、イベントタイプがエラーを示す場合は、以下の追加のステップを実行します。

  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

下記は、失敗に関する情報を保存する一般的なオブジェクトです。

オブジェクト属性値
PaymentIntentlast_payment_errorエラーオブジェクト
SetupIntentlast_setup_errorエラーオブジェクト
Invoice (請求書)last_finalization_errorエラーオブジェクト
SetupAttemptsetup_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

別のパラメーターを渡してリクエストを再試行するなど、予期しないものにべき等キーが使用されました。
権限エラー

Stripe::PermissionError

このリクエストに使用された API キーには必要な権限がありません。
レート制限エラー

Stripe::RateLimitError

短時間のうちに過剰な回数の API コールが行われました。
署名確認エラー

Stripe::SignatureVerificationError

Webhook の署名確認が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。

支払いエラー

支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。

これらのカテゴリーの区別や対応方法について、詳細はエラーコード、拒否コード、支払い結果をご覧ください。

(エラーオブジェクトから支払い結果を見つけるには、最初に、関連する Payment Intent と作成された最新の Chargeを取得します。以下の例でデモンストレーションをご覧ください。)

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

API バージョン 2022-08-01 以前のユーザー:

(エラーオブジェクトから支払い結果を見つけるには、最初に、関連する Payment Intent と 作成された最新の Charge を取得します。下記の例でデモンストレーションをご覧ください。)

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 for Teams の顧客は、以下の追加のオプションを使用できます。

  • 特定の支払いを免除するには、許可リストに追加します。Radar for Fraud Teams
  • リスク許容度を変更するには、リスク設定を調整します。Radar for Fraud Teams
  • 支払いをブロックする基準を変更するには、カスタムルールを使用します。Radar for Fraud Teams

不正利用をシミュレーションするテストカードを使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、Radar のドキュメントに記載されているテストに関するアドバイスに従ってください。

支払いがカード発行会社によって拒否された

タイプ

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.

以下も行うことができます。

成功した支払いと拒否された支払いをシミュレーションするテストカードを使用して、実装で支払い拒否を処理する方法をテストします。

他の支払いエラー

タイプ

Stripe::CardError

問題別の支払いエラーが発生しました。
解決方法このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、エラーコードに関するドキュメントをご覧ください。

無効なリクエストエラー

タイプ

Stripe::InvalidRequestError

問題API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。
解決方法大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。
  • 問題についての詳細は、エラーコードのドキュメントをご覧ください。
  • ご参考までに、 のリンクからエラーコードに関するドキュメントをご覧いただけます。
  • エラーが特定のパラメーターに関連している場合は、 を使用して、そのパラメーターを判断します。

接続エラー

タイプ

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:

  • オブジェクトを作成または更新するときに、べき等キーを使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、低レベルのエラー処理をご覧ください。
  • 自動リトライをオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。

このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。

API エラー

タイプ

Stripe::APIError

問題Stripe 側で問題が発生しました (稀な状況です)。

解決方法

API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。

Webhook を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。

異常な状況下で最大限の堅牢性を得るように実装を設定するには、サーバーエラーに関する詳しい説明をご覧ください。

認証エラー

タイプ

Stripe::AuthenticationError

問題Stripe は、提供された情報では認証できません。
解決方法

べき等エラー

タイプ

Stripe::IdempotencyError

問題別のパラメーターを渡してリクエストを再試行するなど、予期しないものにべき等キーが使用されました。
解決方法
  • べき等キーを使用した後は、同一の 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 コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。
  • レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、レート制限に関するドキュメントをご覧ください。
  • トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前にサポートまでお問い合わせください。

署名確認エラー

タイプ

Stripe::SignatureVerificationError

問題Webhook の署名確認が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。

解決方法

このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、400 Bad Request ステータスコードで応答してください。

受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、Webhook の署名の確認に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc