# エラー処理 支払い拒否、無効なデータ、ネットワークの問題などを検出して応答します。 Stripe は多くの種類のエラーを提供しています。エラーは、支払い拒否やネットワークの中断などの外部のイベントや、無効な API コールなどのコードの問題を反映している場合があります。 ## エラーデータを解析 Stripe が API リクエストにエラーを返すと、エラーの詳細を受け取ります。このガイドの処理に関する推奨事項を適用する方法を理解するのに役立ちます。また、これらの詳細は、必要に応じて Stripe サポートに重要な情報を提供するのに役立ちます。 | プロパティ | 説明 | | ----------------- | ----------------------------------------------------------------------------------------------- | | `code` | エラーコード。 | | `doc_url` | 特定のエラーコードの Stripe ドキュメントへのリンク。 | | `message` | エラーの理由の説明。 | | `param` | エラーが発生したリクエストのパラメーター。 | | `request_log_url` | Stripe ダッシュボードへのリンク。元のリクエストとエラーに関する詳細なログを確認できます。 | | リクエスト ID | エラーが発生した元のリクエストの一意の識別子。エラー応答ヘッダーにはこの値 (`req` で始まる文字列) が含まれますが、このガイドのコード例に示すように、リクエストに出力を指定できます。 | | `type` | このエラーが属するエラーカテゴリーへの参照。 | エラーを処理するには、下記の表に記載されている一部またはすべてのテクニックを使用します。どのテクニックを使用する場合でも、[各エラータイプに推奨される応答](https://docs.stripe.com/error-handling.md#error-types)を使用できます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 緊急の問題によって API コールが続行できなくなった場合、Stripe Ruby ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。 例外を検出するには、Ruby の `rescue` キーワードを使用します。`Stripe::StripeError` またはそのサブクラスを検出して、Stripe 固有の例外のみを処理します。各サブクラスは、それぞれ異なる種類の例外を表します。例外を検出すると、[そのクラスを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)できます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 緊急の問題によって API コールが続行できなくなった場合、Stripe Python ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。 例外を検出するには、Python の `try`/`except` 構文を使用します。`stripe.StripeError` またはそのサブクラスを使用して、Stripe 固有の例外のみを処理します。各サブクラスは、異なる種類の例外を表します。例外を検出すると、[そのクラスを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)できます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 緊急の問題によって API コールが続行できなくなった場合、Stripe PHP ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。 例外を検出するには、PHP の `try`/`catch` 構文を使用します。Stripe は、検出できるいくつかの例外クラスを提供しています。各クラスは、それぞれ異なる種類のエラーを表します。例外を検出すると、[そのクラスを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)できます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 緊急の問題によって API コールが続行できなくなった場合、Stripe Java ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。 例外を検出するには、Java の `try`/`catch` 構文を使用します。`StripeException` またはそのサブクラスを検出して、Stripe 固有の例外のみを処理します。各クラスは、それぞれ異なる種類の例外を表します。例外を検出すると、[そのクラスを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)できます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 差し迫った問題によって API コールを続行できない場合、Stripe Node.js ライブラリが例外を発生させることがあります。例外をキャッチして処理することがベストプラクティスです。例外を発生させてキャッチできるようにするには、次の操作を行います。 - 関数で API コールを行う場合、関数定義の前に `async` キーワードを指定します。 - API コール自体の前に `await` キーワードを指定します。 - API コールを `try`/`catch` ブロックにラップします。 例外を検出すると、[そのタイプ属性を使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)することができます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [エラーの値を使用](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## エラーの値を使用する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスをエラーの値に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 Stripe Go ライブラリの API コールは、結果の値とエラーの値の両方が返されます。両方ともキャプチャーするには、複数の割り当てを使用します。エラーの値が `nil` でない場合は、緊急の問題によって API コールの続行が妨げられたことを示しています。 エラーの値が Stripe に関連している場合、問題を記述するフィールドを持つ `stripe.Error` オブジェクトにキャストすることができます。[Type フィールドを使用してレスポンスを選択](https://docs.stripe.com/error-handling.md#error-types)します。場合によっては、追加情報を含むより明細なエラータイプに `Err` プロパティを指定することができます。 | テクニック | 目的 | 必要な場合 | | ------------------------------------------------------------------------------------ | --------------------- | ----- | | [例外の検出](https://docs.stripe.com/error-handling.md#catch-exceptions) | API コールが続行できない場合の回復 | 常時 | | [Webhook の監視](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Stripe からの通知への応答 | ときどき | | [失敗に関する保存された情報の取得](https://docs.stripe.com/error-handling.md#use-stored-information) | 過去の問題の調査と他のテクニックのサポート | ときどき | ## 例外を検出する このライブラリでは、200 以外の HTTP レスポンスを確認する必要はありません。ライブラリはそのレスポンスを例外に変換します。 稀なケースで HTTP の詳細が必要になった場合は、[低レベルの例外の処理](https://docs.stripe.com/error-low-level.md)および [Error (エラー)](https://docs.stripe.com/api/errors.md) オブジェクトを参照してください。 緊急の問題によって API コールが続行できなくなった場合、Stripe .NET ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。 例外を検出するには、.NET の `try`/`catch` 構文を使用します。`StripeException` を検出し、[その Type 属性を使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' def example_function(params) begin Stripe::PaymentIntent.create(params) rescue Stripe::CardError => e puts "A payment error occurred: #{e.error.message} (request id: #{e.request_id})" rescue Stripe::InvalidRequestError => e puts "An invalid request occurred. (request id: #{e.request_id})" # Add additional catch cases for other Stripe exception types as needed. # See all exception types at https://docs.stripe.com/api/errors/handling?lang=ruby rescue Stripe::StripeError => e # All other Stripe errors puts "Status: #{e.http_status}, Code: #{e.code}, Message: #{e.message}, Request ID: #{e.request_id}" else puts "No error." end end ``` 例外処理を設定した後、[テストカード](https://docs.stripe.com/testing.md)などの各種データでテストを行い、さまざまな支払いの結果をシミュレートします。 #### トリガーするエラー - 無効なリクエスト #### Ruby ```ruby example_function( # The required parameter currency is missing, amount: 2000, confirm: true, payment_method: 'pm_card_visa', # これは、テスト環境で使用すると常に成功の結果が返されるテストカードです。これと他のテストカードを併用して、システムでのエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` An invalid request occurred. ``` #### トリガーするエラー - カードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedFraudulent', # これは、必ず不正請求の支払いエラーを発生させるテストカードです。このテストカードや他のテストカードを使用して、組み込みのエラー処理をテストします。本番環境のコードでは、実際の支払い方法を使用します。 ) ``` ``` A payment error occurred: Your card was declined. ``` #### トリガーするエラー - エラーなし #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa', # これは、テスト環境で使用すると常に成功の結果が返されるテストカードです。これと他のテストカードを併用して、システムでのエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` No error. ``` ## Webhook を監視する Stripe は、*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用してさまざまな種類の問題を通知します。これには、API コールの直後に発生する問題以外も含まれます。以下に例を紹介します。 - 不審請求の申請についての主張が認められなかった。 - 継続支払いが数か月成功した後に失敗した。 - フロントエンドが支払いを*確定* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment)したが、支払いの失敗を検出する前にオフラインになった (バックエンドは、API コールを行っていなくても、Webhook 通知を受信します)。 すべての Webhook イベントタイプを処理する必要はありません。実際、何も処理しない実装もあります。 Webhook ハンドラで、[Webhook ビルダー](https://docs.stripe.com/webhooks/quickstart.md)の基本的なステップから開始します。Event オブジェクトを取得し、イベントタイプを使用して何が起こったかを調べます。次に、イベントタイプがエラーを示す場合は、以下の追加のステップを実行します。 1. [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) にアクセスして、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. [event[‘data’][‘object’]](https://docs.stripe.com/api/events/object.md#event_object-data-object) にアクセスして、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. [event->data->object](https://docs.stripe.com/api/events/object.md#event_object-data-object) にアクセスして、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. `EventDataObjectDeserializer` を使用して、出力を適切なタイプにキャストすることで、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) にアクセスして、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. `event.Data.Raw` からデータをアンマーシャルすることで、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 1. [stripeEvent.Data.Object](https://docs.stripe.com/api/events/object.md#event_object-data-object) を適切なタイプにキャストして、影響を受けたオブジェクトを取得します。 1. 影響を受けたオブジェクトの[保存された情報を使用](https://docs.stripe.com/error-handling.md#use-stored-information)して、エラーオブジェクトを含むコンテキストを取得します。 1. [タイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)します。 #### Ruby ```ruby 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 イベントをトリガー](https://docs.stripe.com/webhooks.md#test-webhook)することができます。リンクで設定のステップを完了した後、失敗した支払いをトリガーして、結果のエラーメッセージを表示します。 ```bash stripe trigger payment_intent.payment_failed ``` ```bash A payment error occurred: Your card was declined. ``` ## 失敗に関する保存された情報を取得する 多くのオブジェクトは、失敗に関する情報を保存します。そのため、何らかの問題が発生している場合は、オブジェクトを取得して詳細を調べることができます。多くの場合、保存された情報はエラーオブジェクトの形式であり、[そのタイプを使用して応答を選択](https://docs.stripe.com/error-handling.md#error-types)することができます。 例: 1. 特定の支払いインテントを取得します。 1. [last_payment_error](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error) が空であるかどうかを判断して、支払いエラーが発生したかどうかを確認します。 1. エラーが発生していた場合は、タイプと影響を受けたオブジェクトを含めてエラーをログに記録します。 #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` 下記は、失敗に関する情報を保存する一般的なオブジェクトです。 | オブジェクト | 属性 | 値 | | --------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------- | | [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) | `last_payment_error` | [エラーオブジェクト](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [SetupIntent](https://docs.stripe.com/api/setup_intents.md) | `last_setup_error` | [エラーオブジェクト](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Invoice (請求書)](https://docs.stripe.com/api/invoices.md) | `last_finalization_error` | [エラーオブジェクト](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [SetupAttempt](https://docs.stripe.com/api/setup_attempts.md) | `setup_error` | [エラーオブジェクト](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [入金](https://docs.stripe.com/api/payouts.md) | `failure_code` | [入金失敗コード](https://docs.stripe.com/api/payouts/failures.md) | | [返金](https://docs.stripe.com/api/refunds.md) | `failure_reason` | [返金失敗コード](https://docs.stripe.com/api/refunds/object.md#refund_object-failure_reason) | 失敗に関する保存情報を使用してコードをテストする場合、失敗した取引のシミュレーションが必要になることがよくあります。大抵の場合、そのための[テストカード](https://docs.stripe.com/testing.md)またはテスト用の銀行口座番号を使用できます。以下はその例です。 - [拒否された支払いをシミュレート](https://docs.stripe.com/testing.md#declined-payments)して、失敗した Charge、PaymentIntent、SetupIntent などを作成します。 - [入金の失敗をシミュレート](https://docs.stripe.com/connect/testing.md#account-numbers)します。 - [返金の失敗をシミュレート](https://docs.stripe.com/testing.md#refunds)します。 ## エラーのタイプと応答 Stripe Ruby ライブラリでは、エラーオブジェクトは `stripe.error.StripeError` およびそのサブクラスに属します。応答方法については、各クラスのドキュメントをご覧ください。 | 名前 | クラス | 説明 | | ----------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [Stripe::CardError](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [Stripe::InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [Stripe::APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [Stripe::APIError](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [Stripe::AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [Stripe::IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [Stripe::PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [Stripe::RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [Stripe::SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [Stripe::CardError](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `Stripe::CardError` | | **コード** | ```ruby charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `Stripe::CardError` | | **コード** | `e.error.code == "card_declined"` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `Stripe::CardError` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `Stripe::InvalidRequestError` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、 のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、 を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `Stripe::APIConnectionError` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `Stripe::APIError` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `Stripe::AuthenticationError` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `Stripe::IdempotencyError` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `Stripe::PermissionError` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `Stripe::RateLimitError` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `Stripe::SignatureVerificationError` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 | Stripe Python ライブラリでは、エラーオブジェクトは `stripe.StripeError` とそのサブクラスを呼び出します。応答方法については、各クラスのドキュメントを使用してください。 | 名前 | クラス | 説明 | | ----------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [stripe.CardError](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [stripe.InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [stripe.APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [stripe.APIError](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [stripe.AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [stripe.IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [stripe.PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [stripe.RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [stripe.SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [stripe.CardError](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `stripe.CardError` | | **コード** | ```python charge = stripe.Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `stripe.CardError` | | **コード** | `e.code == "card_declined"` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `stripe.CardError` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `stripe.InvalidRequestError` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、`e.doc_url` のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、`e.param` を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `stripe.APIConnectionError` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `stripe.APIError` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `stripe.AuthenticationError` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `stripe.IdempotencyError` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `stripe.PermissionError` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `stripe.RateLimitError` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `stripe.SignatureVerificationError` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 | Stripe PHP ライブラリでは、各タイプのエラーはそれぞれのクラスに属します。応答方法については、各クラスのドキュメントをご覧ください。 | 名前 | クラス | 説明 | | ----------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [Stripe\Exception\InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [Stripe\Exception\ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [Stripe\Exception\ApiErrorException](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [Stripe\Exception\AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [Stripe\Exception\IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [Stripe\Exception\PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [Stripe\Exception\RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [Stripe\Exception\SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `Stripe\Exception\CardException` | | **コード** | ```php $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); $charge->outcome->type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `Stripe\Exception\CardException` | | **コード** | `$e->getError()->code == "card_declined"` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `Stripe\Exception\CardException` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `Stripe\Exception\InvalidRequestException` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、`e->getError()->doc_url` のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、`e->getError()->param` を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `Stripe\Exception\ApiConnectionException` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `Stripe\Exception\APIException` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `Stripe\Exception\AuthenticationException` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `Stripe\Exception\IdempotencyException` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `Stripe\Exception\PermissionException` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `Stripe\Exception\RateLimitException` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `Stripe\Exception\SignatureVerificationException` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 | Stripe Java ライブラリでは、各タイプのエラーはそれぞれのクラスに属します。応答方法については、各クラスのドキュメントをご覧ください。 | 名前 | クラス | 説明 | | ----------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [CardException](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [APIException](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [CardException](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `CardException` | | **コード** | ```java Charge charge = Charge.retrieve(ex.getStripeError() .getPaymentIntent() .getLatestCharge()); charge.getOutcome().getType() == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `CardException` | | **コード** | `e.getCode() == "card_declined"` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `CardException` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `InvalidRequestException` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、`e.getDocUrl()` のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、`e.getParam()` を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `APIConnectionException` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `APIException` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `AuthenticationException` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `IdempotencyException` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `PermissionException` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `RateLimitException` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `SignatureVerificationException` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 | Stripe Node.js ライブラリでは、各エラーオブジェクトに `type` 属性が設定されています。応答方法については、各タイプのドキュメントをご覧ください。 | 名前 | タイプ | 説明 | | ----------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [StripeCardError](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [StripeInvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [StripeConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [StripeAPIError](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [StripeAuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [StripeIdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [StripePermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [StripeRateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [StripeSignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [StripeCardError](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `StripeCardError` | | **コード** | ```javascript const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge) charge.outcome.type === 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `e.payment_intent.charges.data[0].outcome.type === 'blocked'` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `StripeCardError` | | **コード** | `e.code === 'card_declined'` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `StripeCardError` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `StripeInvalidRequestError` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、`e.doc_url` のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、`e.param` を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `StripeAPIConnectionError` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `StripeAPIError` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `StripeAuthenticationError` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `StripeIdempotencyError` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `StripePermissionError` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `StripeRateLimitError` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `StripeSignatureVerificationError` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 | Stripe Go ライブラリでは、各エラーオブジェクトに `Type` 属性が設定されています。応答方法については、各タイプのドキュメントをご覧ください。 | 名前 | タイプ | 説明 | | ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [stripe.ErrorTypeCard](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [stripe.ErrorTypeInvalidRequest](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 現在有効ではない方法で API コールが行われました。これには以下が含まれます。 - [レート制限エラー](https://docs.stripe.com/error-handling.md#rate-limiting) - [認証エラー](https://docs.stripe.com/error-handling.md#authentication-errors) - [無効なパラメーターまたは状態](https://docs.stripe.com/error-handling.md#invalid-parameters-or-state) | | API エラー | [stripe.ErrorTypeAPI](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | べき等エラー | [stripe.ErrorTypeIdempotency](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | ## カードエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [stripe.ErrorTypeCard](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 不正使用の疑いのためにブロックされた | | | | | **タイプ** | `stripe.ErrorTypeCard` | | **コード** | ```go charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### カード発行会社によって拒否された | | | | | **タイプ** | `stripe.ErrorTypeCard` | | **コード** | `cardErr.Error.Code == stripe.ErrorCodeCardDeclined` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `stripe.ErrorTypeCard` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー 無効なリクエストエラーは、さまざまな状況で発生します。最も一般的な状況は、API リクエストが無効なパラメーターを含んでいるか、現在の実装状態では許可されていない場合です。エラーコード (`stripeErr.Code`) を使用して、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)を参照し、解決策を見つけます。いくつかのエラーコードには特別なレスポンスが必要になります。 - `rate_limit` および `lock_timeout` は[レート制限エラー](https://docs.stripe.com/error-handling.md#rate-limit-errors)を反映しています - `secret_key_required` は[認証エラー](https://docs.stripe.com/error-handling.md#authentication-errors)を反映しています - その他のエラーコードは[無効なパラメーターまたは状態](https://docs.stripe.com/error-handling.md#other-invalid-request-errors)を反映しています ### レート制限エラー | | | | | **タイプ** | `stripe.ErrorTypeInvalidRequest` | | **コード** | `stripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ### 認証エラー | | | | | **タイプ** | `stripe.ErrorTypeInvalidRequest` | | **コード** | `stripeErr.Code == stripe.ErrorCodeSecretKeyRequired` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ### 無効なパラメーターまたは状態 | | | | | **タイプ** | `stripe.ErrorTypeInvalidRequest` | | **コード** | `stripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、`stripeErr.DocURL` のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、`stripeErr.Param` を使用して、そのパラメーターを判断します。 | ## API エラー | | | | | **タイプ** | `stripe.ErrorTypeAPI` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## べき等エラー | | | | | **タイプ** | `stripe.ErrorTypeIdempotency` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | Stripe .NET ライブラリでは、各エラーオブジェクトに `type` 属性が設定されています。応答方法については、各タイプのドキュメントをご覧ください。 | 名前 | タイプ | 説明 | | ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 支払いエラー | [card_error](https://docs.stripe.com/error-handling.md#payment-errors) | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined)。 - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors)。 | | 無効なリクエストエラー | [invalid_request_error](https://docs.stripe.com/error-handling.md#invalid-request-errors) | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | 接続エラー | [api_connection_error](https://docs.stripe.com/error-handling.md#connection-errors) | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | API エラー | [api_error](https://docs.stripe.com/error-handling.md#api-errors) | Stripe 側で問題が発生しました (稀な状況です)。 | | 認証エラー | [authentication_error](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe は、提供された情報では認証できません。 | | べき等エラー | [idempotency_error](https://docs.stripe.com/error-handling.md#idempotency-errors) | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | 権限エラー | [permission_error](https://docs.stripe.com/error-handling.md#permission-errors) | このリクエストに使用された API キーには必要な権限がありません。 | | レート制限エラー | [rate_limit_error](https://docs.stripe.com/error-handling.md#rate-limit-errors) | 短時間のうちに過剰な回数の API コールが行われました。 | | 署名確認エラー | [signature_verification_error](https://docs.stripe.com/error-handling.md#signature-verification-errors) | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | ## 支払いエラー このセクションのすべての内容はカード以外の決済にも適用されます。これまでの経緯から、支払いエラーのタイプには [card_error](https://docs.stripe.com/error-handling.md#card-error) があります。ただし、実際には決済手段に関係なく、あらゆる支払いの問題を表す可能性があります。 支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。 - [支払いが不正使用の疑いのためにブロックされました](https://docs.stripe.com/error-handling.md#payment-blocked) - [支払いがカード発行会社によって拒否されました](https://docs.stripe.com/error-handling.md#payment-declined) - [他の支払いエラー](https://docs.stripe.com/error-handling.md#other-payment-errors) これらのカテゴリーの区別や対応方法について、詳細は[エラーコード](https://docs.stripe.com/error-codes.md)、[拒否コード](https://docs.stripe.com/declines/codes.md)、[支払い結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)をご覧ください。 (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と[作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge)を取得します。以下の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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](https://docs.stripe.com/upgrades.md#2022-08-01) 以前のユーザー: (エラーオブジェクトから支払い結果を見つけるには、最初に、[関連する Payment Intent](https://docs.stripe.com/api/errors.md#errors-payment_intent) と [作成された最新の Charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data) を取得します。下記の例でデモンストレーションをご覧ください。) #### Ruby ```ruby require 'stripe' Stripe.api_key = '<>' 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 ``` テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。 - [不正利用のリスクのためにブロックされる支払いをシミュレーションする](https://docs.stripe.com/testing.md#fraud-prevention) - [拒否された支払いと他のカードエラーをシミュレーションする](https://docs.stripe.com/testing.md#declined-payments) 以下のテストコードは、いくつかの可能性を示しています。 #### トリガーするエラー - 不正使用の疑いのためにブロックされた #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_radarBlock', # これは、サンドボックスで使用する際に、必ず不正利用の疑いでブロックされるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment blocked for suspected fraud. ``` #### トリガーするエラー - カード発行会社によって拒否された #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_visa_chargeDeclined', # これは、サンドボックスで使用する際に、必ずカード発行会社によって拒否されるテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Payment declined by the issuer. ``` #### トリガーするエラー - 期限切れのカード #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedExpiredCard', # これは、サンドボックスで使用する際に、必ず期限切れで失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Card expired. ``` #### トリガーするエラー - 他のカードエラー #### Ruby ```ruby example_function( currency: 'usd', amount: 2000, confirm: true, payment_method: 'pm_card_chargeDeclinedProcessingError', # これは、サンドボックスで使用する際に、必ず処理エラーによって失敗するテストカードです。このカードや他のテストカードを使用して、実装のエラー処理をテストします。本番用コードでは、ここで実際の決済手段を使用します。 ) ``` ``` Other payment error. ``` ### 支払いが不正使用の疑いのためにブロックされた | | | | | **タイプ** | `card_error` | | **コード** | ```dotnet var chargeService = new ChargeService(); var options = new ChargeGetOptions(); var charge = chargeService.Get(e.StripeError.PaymentIntent.LatestChargeId, options); charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **コード** | `e.StripeError.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **問題** | | Stripe の不正使用防止システムである *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) によって支払いがブロックされました | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。 - [Radar 導入を最適化](https://docs.stripe.com/radar/optimize-fraud-signals.md) して、より詳細な情報を収集します。 - 構築済みの最適化されたフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 *Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) の顧客は、以下の追加のオプションを使用できます。 - 特定の支払いを免除するには、許可リストに追加します。(Radar for Fraud Teams) - リスク許容度を変更するには、[リスク設定](https://docs.stripe.com/radar/risk-settings.md)を調整します。(Radar for Fraud Teams) - 支払いをブロックする基準を変更するには、[カスタムルール](https://docs.stripe.com/radar/rules.md)を使用します。(Radar for Fraud Teams) [不正利用をシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、[Radar のドキュメント](https://docs.stripe.com/radar/testing.md)に記載されているテストに関するアドバイスに従ってください。 | ### 支払いがカード発行会社によって拒否された | | | | | **タイプ** | `card_error` | | **コード** | `e.StripeError.Code == "card_declined"` | | **問題** | カード発行会社によって支払いが拒否されました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、[拒否コードに関するドキュメント](https://docs.stripe.com/declines/codes.md)をご覧ください。 以下も行うことができます。 - [カード発行会社による支払い拒否を削減するための推奨事項に従います](https://docs.stripe.com/declines/card.md#reducing-bank-declines)。 - これらの推奨事項を実装する構築済みのフォームエレメントには、[Payment Links](https://docs.stripe.com/payment-links.md)、[Checkout](https://docs.stripe.com/payments/checkout.md)、または [Stripe Elements](https://docs.stripe.com/payments/elements.md) を使用します。 [成功した支払いと拒否された支払いをシミュレーションするテストカード](https://docs.stripe.com/radar/testing.md)を使用して、実装で支払い拒否を処理する方法をテストします。 | ### 他の支払いエラー | | | | | **タイプ** | `card_error` | | **問題** | 別の支払いエラーが発生しました。 | | **解決方法** | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、[エラーコードに関するドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 | ## 無効なリクエストエラー | | | | | **タイプ** | `invalid_request_error` | | **問題** | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 | | **解決方法** | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。 - 問題についての詳細は、[エラーコードのドキュメント](https://docs.stripe.com/error-codes.md)をご覧ください。 - ご参考までに、 のリンクからエラーコードに関するドキュメントをご覧いただけます。 - エラーが特定のパラメーターに関連している場合は、 を使用して、そのパラメーターを判断します。 | ## 接続エラー | | | | | **タイプ** | `api_connection_error` | | **問題** | お客様のサーバーと Stripe の間でネットワークの問題が発生しました。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功したか失敗したかを断定しないでください。 成功したかどうかを確認するには、以下のようにします。 - 関連オブジェクトを Stripe から取得して、ステータスを確認します。 - 操作の成功または失敗を示す Webhook 通知をリッスンします。 接続エラーから回復するには、以下を実行できます。 - オブジェクトを作成または更新するときに、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。これにより、接続エラーが発生した場合に、2 つ目のオブジェクトを作成することや 2 度更新するリスクを生じることなく、リクエストを安全に繰り返すことができます。成功または失敗の明確な結果を得られるまで、同じべき等キーを使用してリクエストを繰り返します。この対策に関する高度なアドバイスについては、[低レベルのエラー処理](https://docs.stripe.com/error-low-level.md#idempotency)をご覧ください。 - [自動リトライ](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries) をオンにします。これにより、Stripe は自動的にべき等キーを生成して、安全な状況でリクエストを繰り返します。 このエラーにより他のエラーが隠される場合があり、接続エラーが解決された後で他のエラーが明らかになる可能性があります。元のリクエストと同じように、これらのすべての解答にエラーがないかを確認してください。 | ## API エラー | | | | | **タイプ** | `api_error` | | **問題** | Stripe 側で問題が発生しました (稀な状況です)。 | | **解決方法** | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、[サーバーエラーに関する詳しい説明](https://docs.stripe.com/error-low-level.md#server-errors)をご覧ください。 | ## 認証エラー | | | | | **タイプ** | `authentication_error` | | **問題** | Stripe は、提供された情報では認証できません。 | | **解決方法** | - 正しい [API キー](https://docs.stripe.com/keys.md)を使用してください。 - [「ローテーション」または取り消しを行った](https://docs.stripe.com/keys.md#rolling-keys)キーを使用していないことを確認してください。 | ## べき等エラー | | | | | **タイプ** | `idempotency_error` | | **問題** | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)が使用されました。 | | **解決方法** | - べき等キーを使用した後は、同一の API コールでのみ再使用してください。 - 255 文字の制限内でべき等キーを使用してください。 | ## 権限エラー | | | | | **タイプ** | `permission_error` | | **問題** | このリクエストに使用された API キーには必要な権限がありません。 | | **解決方法** | - アクセスできないサービスに[制限付き API キー](https://docs.stripe.com/keys-best-practices.md#limit-access)を使用していないことを確認してください。 - 権限が不足している[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)でログインしているときは、ダッシュボードでアクションを実行しないでください。 | ## レート制限エラー | | | | | **タイプ** | `rate_limit_error` | | **問題** | 短時間のうちに過剰な回数の API コールが行われました。 | | **解決方法** | - 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。 - レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、[レート制限](https://docs.stripe.com/rate-limits.md)に関するドキュメントをご覧ください。 - トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前に[サポートまでお問い合わせください](https://support.stripe.com/)。 | ## 署名確認エラー | | | | | **タイプ** | `signature_verification_error` | | **問題** | *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) の[署名確認](https://docs.stripe.com/webhooks.md#verify-events)が使用されており、Webhook イベントが本物であるかどうかを確認できませんでした。 | | **解決方法** | このエラーは、組み込みが正常に機能している場合でも発生することがあります。Webhook の署名確認を使用する際に、サードパーティーが偽物の Webhook や悪意のある Webhook の送信を試みると、確認が失敗してこのエラーが発生します。このエラーを検出して、`400 Bad Request` ステータスコードで応答してください。 受け取るはずがないエラーを受け取った場合、(Webhook の発信者が Stripe であることが明らかな場合など)、[Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)に関するドキュメントをご覧ください。具体的には、正しいエンドポイントシークレットを使用していることを確認します。これは、API キーとは別のものです。 |