エラー処理
支払い拒否、無効なデータ、ネットワークの問題などを検出して応答します。
Stripe は多くの種類のエラーを提供しています。エラーは、支払い拒否やネットワークの中断などの外部のイベントや、無効な API コールなどのコードの問題を反映している場合があります。
エラーを処理するには、下記の表に記載されている一部またはすべてのテクニックを使用します。どのテクニックを使用する場合でも、各エラータイプに推奨される応答を使用できます。
テクニック | 目的 | 必要な場合 |
---|---|---|
エラーの値を使用 | API コールが続行できない場合の回復 | 常時 |
Webhook の監視 | Stripe からの通知への応答 | ときどき |
失敗に関する保存された情報の取得 | 過去の問題の調査と他のテクニックのサポート | ときどき |
エラーの値を使用する
Stripe Go ライブラリの API コールは、結果の値とエラーの値の両方が返されます。両方ともキャプチャーするには、複数の割り当てを使用します。エラーの値が nil
でない場合は、緊急の問題によって API コールの続行が妨げられたことを示しています。
エラーの値が Stripe に関連している場合、問題を記述するフィールドを持つ stripe.
オブジェクトにキャストすることができます。Type フィールドを使用してレスポンスを選択します。場合によっては、追加情報を含むより明細なエラータイプに Err
プロパティを指定することができます。
例外処理を設定した後、テストカードなどの各種データでテストを行い、さまざまな支払いの結果をシミュレートします。
Webhook を監視する
Stripe は、Webhook を使用してさまざまな種類の問題を通知します。これには、API コールの直後に発生する問題以外も含まれます。以下に例を紹介します。
- 不審請求の申請についての主張が認められなかった。
- 継続支払いが数か月成功した後に失敗した。
- フロントエンドが支払いを確定したが、支払いの失敗を検出する前にオフラインになった (バックエンドは、API コールを行っていなくても、Webhook 通知を受信します)。
すべての Webhook イベントタイプを処理する必要はありません。実際、何も処理しない実装もあります。
Webhook ハンドラで、Webhook ビルダーの基本的なステップから開始します。Event オブジェクトを取得し、イベントタイプを使用して何が起こったかを調べます。次に、イベントタイプがエラーを示す場合は、以下の追加のステップを実行します。
event.
からデータをアンマーシャルすることで、影響を受けたオブジェクトを取得します。Data. Raw - 影響を受けたオブジェクトの保存された情報を使用して、エラーオブジェクトを含むコンテキストを取得します。
- タイプを使用して応答を選択します。
お客様のシステムが Webhook イベントにどのように応答するかテストするために、ローカルの Webhook イベントをトリガーすることができます。リンクで設定のステップを完了した後、失敗した支払いをトリガーして、結果のエラーメッセージを表示します。
stripe trigger payment_intent.payment_failed
A payment error occurred: Your card was declined.
失敗に関する保存された情報を取得する
多くのオブジェクトは、失敗に関する情報を保存します。そのため、何らかの問題が発生している場合は、オブジェクトを取得して詳細を調べることができます。多くの場合、保存された情報はエラーオブジェクトの形式であり、そのタイプを使用して応答を選択することができます。
例:
- 特定の支払いインテントを取得します。
- last_payment_error が空であるかどうかを判断して、支払いエラーが発生したかどうかを確認します。
- エラーが発生していた場合は、タイプと影響を受けたオブジェクトを含めてエラーをログに記録します。
下記は、失敗に関する情報を保存する一般的なオブジェクトです。
オブジェクト | 属性 | 値 |
---|---|---|
PaymentIntent | last_ | エラーオブジェクト |
SetupIntent | last_ | エラーオブジェクト |
Invoice (請求書) | last_ | エラーオブジェクト |
SetupAttempt | setup_ | エラーオブジェクト |
入金 | failure_ | 入金失敗コード |
返金 | failure_ | 返金失敗コード |
失敗に関する保存情報を使用してコードをテストする場合、失敗した取引のシミュレーションが必要になることがよくあります。大抵の場合、そのためのテストカードまたはテスト用の銀行口座番号を使用できます。以下はその例です。
- 拒否された支払いをシミュレートして、失敗した Charge、PaymentIntent、SetupIntent などを作成します。
- 入金の失敗をシミュレートします。
- 返金の失敗をシミュレートします。
エラーのタイプと応答
Stripe Go ライブラリでは、各エラーオブジェクトに Type
属性が設定されています。応答方法については、各タイプのドキュメントをご覧ください。
名前 | タイプ | 説明 |
---|---|---|
支払いエラー | 決済時にエラーが発生して、以下のいずれかの状況が発生しています。 | |
無効なリクエストエラー | 現在有効ではない方法で API コールが行われました。これには以下が含まれます。 | |
API エラー | Stripe 側で問題が発生しました (稀な状況です)。 | |
べき等エラー | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものにべき等キーが使用されました。 |
カードエラー
支払いエラー (歴史的理由から「カードエラー」と呼ばれることもあります) は、幅広い一般的な問題から発生し、以下の 3 つのカテゴリーに分類されます。
これらのカテゴリーの区別や対応方法について、詳細はエラーコード、拒否コード、支払い結果をご覧ください。
(エラーオブジェクトから支払い結果を見つけるには、最初に、関連する Payment Intent と作成された最新の Chargeを取得します。以下の例でデモンストレーションをご覧ください。)
API バージョン 2022-08-01 以前のユーザー:
(エラーオブジェクトから支払い結果を見つけるには、最初に、関連する Payment Intent と 作成された最新の Charge を取得します。下記の例でデモンストレーションをご覧ください。)
テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。
以下のテストコードは、いくつかの可能性を示しています。
不正使用の疑いのためにブロックされた
タイプ |
|
コード |
|
コード |
|
問題 | Stripe の不正使用防止システムである Radar によって支払いがブロックされました |
解決方法 | このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。 正当な支払いのブロックを減らすには、以下を試します。
Radar for Teams の顧客は、以下の追加のオプションを使用できます。
不正利用をシミュレーションするテストカードを使用して、実装の設定をテストできます。カスタムの Radar ルールを使用している場合は、Radar のドキュメントに記載されているテストに関するアドバイスに従ってください。 |
カード発行会社によって拒否された
タイプ |
|
コード |
|
問題 | カード発行会社によって支払いが拒否されました。 |
解決方法 | このエラーは、実装が正常に機能している場合でも発生することがあります。このエラーは、カード発行会社によるアクションを反映しており、そのアクションは正当である可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、拒否コードに関するドキュメントをご覧ください。 以下も行うことができます。
成功した支払いと拒否された支払いをシミュレーションするテストカードを使用して、実装で支払い拒否を処理する方法をテストします。 |
他の支払いエラー
タイプ |
|
問題 | 別の支払いエラーが発生しました。 |
解決方法 | このエラーは、実装が正常に機能している場合でも発生することがあります。適切な次のステップを判断するには、エラーコードを使用します。各コードに対する適切な対応については、エラーコードに関するドキュメントをご覧ください。 |
無効なリクエストエラー
無効なリクエストエラーは、さまざまな状況で発生します。最も一般的な状況は、API リクエストが無効なパラメーターを含んでいるか、現在の実装状態では許可されていない場合です。エラーコード (stripeErr.
) を使用して、エラーコードに関するドキュメントを参照し、解決策を見つけます。いくつかのエラーコードには特別なレスポンスが必要になります。
rate_
およびlimit lock_
はレート制限エラーを反映していますtimeout secret_
は認証エラーを反映していますkey_ required - その他のエラーコードは無効なパラメーターまたは状態を反映しています
レート制限エラー
タイプ |
|
コード | stripeErr. |
問題 | 短時間のうちに過剰な回数の API コールが行われました。 |
解決方法 |
|
認証エラー
タイプ |
|
コード | stripeErr. |
問題 | Stripe は、提供された情報では認証できません。 |
解決方法 |
|
無効なパラメーターまたは状態
タイプ |
|
コード | stripeErr. |
問題 | API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。 |
解決方法 | 大半の場合、問題はリクエスト自体にあります。パラメーターが無効であるか、組み込みの現在の状態では実行でないかのどちらかです。
|
API エラー
タイプ |
|
問題 | Stripe 側で問題が発生しました (稀な状況です)。 |
解決方法 | API コールの結果は不確定なものとして扱います。成功または失敗の断定をしないでください。 Webhook を使用して結果に関する情報を確認します。可能な限り、Stripe は問題を解決するときに作成する新しいオブジェクトに関する Webhook を送信します。 異常な状況下で最大限の堅牢性を得るように実装を設定するには、サーバーエラーに関する詳しい説明をご覧ください。 |
べき等エラー
タイプ |
|
問題 | 別のパラメーターを渡してリクエストを再試行するなど、予期しないものにべき等キーが使用されました。 |
解決方法 |
|