コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要
バージョン管理
API バージョンのアップグレード
Essentials
ツール
Visual Studio Code をご利用の場合
機能
Stripe 健全性アラートファイルのアップロード
AI ソリューション
モデルコンテキストプロトコル
セキュリティとプライバシー
Stripe を拡張する
パートナー
パートナー認定

注

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

エラー処理

支払い拒否、無効なデータ、ネットワークの問題などを検出して応答します。

Stripe は多くの種類のエラーを提供しています。エラーは、支払い拒否やネットワークの中断などの外部のイベントや、無効な API コールなどのコードの問題を反映している場合があります。

Parse error data

When Stripe returns an error to your API request, you receive details about the error that help you understand how to apply the handling suggestions in this guide. These details also help you provide important information to Stripe support, if needed.

Property 説明
codeThe error code.
doc_urlA link to the Stripe documentation for the specific error code.
messageA description of the reason for the error.
paramThe parameter of the request that caused the error.
request_log_urlA link to the Stripe Dashboard where you can see detailed logs about the originating request and the error.
リクエスト IDA unique identifier for the originating request that errored. The error response header includes this value (string beginning with req), but you can specify a print in your request, as shown in the code samples in this guide.
typeA reference to the error category this error belongs to.

エラーを処理するには、下記の表に記載されている一部またはすべてのテクニックを使用します。どのテクニックを使用する場合でも、各エラータイプに推奨される応答を使用できます。

テクニック目的必要な場合
例外の検出API コールが続行できない場合の回復常時
Webhook の監視Stripe からの通知への応答ときどき
失敗に関する保存された情報の取得過去の問題の調査と他のテクニックのサポートときどき

例外を検出する

緊急の問題によって API コールが続行できなくなった場合、Stripe PHP ライブラリは例外を発生させます。これは、例外を検出して処理するためのベストプラクティスです。

例外を検出するには、PHP の try/catch 構文を使用します。Stripe は、検出できるいくつかの例外クラスを提供しています。各クラスは、それぞれ異なる種類のエラーを表します。例外を検出すると、そのクラスを使用して応答を選択できます。

Ruby
Python
PHP
Java
Node
Go
.NET
No results
<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

function example_function($args) {
  try {
    $stripe->paymentIntents->create($args);
    error_log("No error.");
  } catch(\Stripe\Exception\CardException $e) {
    error_log("A payment error occurred: {$e->getError()->message}. (request id: {$e->getRequestId()})");
  } catch (\Stripe\Exception\InvalidRequestException $e) {
    error_log("An invalid request occurred. (request id: {$e->getRequestId()})");
  } catch (Exception $e) {
    error_log("Another problem occurred, maybe unrelated to Stripe.");
  }
}

例外処理を設定した後、テストカードなどの各種データでテストを行い、さまざまな支払いの結果をシミュレートします。

Ruby
Python
PHP
Java
Node
Go
.NET
No results
example_function([
  // The required parameter currency is missing
  'amount' => 2000,
  'confirm' => True,
  'payment_method' => 
'pm_card_visa'
,
]);
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
An invalid request occurred.

Webhook を監視する

Stripe は、Webhook を使用してさまざまな種類の問題を通知します。これには、API コールの直後に発生する問題以外も含まれます。以下に例を紹介します。

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

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

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

  1. event->data->object にアクセスして、影響を受けたオブジェクトを取得します。
  2. 影響を受けたオブジェクトの保存された情報を使用して、エラーオブジェクトを含むコンテキストを取得します。
  3. タイプを使用して応答を選択します。
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

$payload = @file_get_contents('php://input');
$event = null;

// Get the event object
try {
  $event = \Stripe\Event::constructFrom(
    json_decode($payload, true)
  );
} catch(\UnexpectedValueException $e) {
  echo '⚠️  Webhook error while parsing basic request.';
  http_response_code(400);
  exit();
}

// Use the event type to find out what happened
if ($event->type == 'payment_intent.payment_failed') {

  // Get the object affected
  $paymentIntent = $event->data->object;

  // Use stored information to get an error object
  $e = $paymentIntent->last_payment_error;

  // Use its type to choose a response
  switch ($e->type) {
    case \Stripe\Exception\CardException:
      error_log("A payment error occurred: {$e->getError()->message}");
      break;
    case \Stripe\Exception\InvalidRequestException:
      error_log("An invalid request occurred.");
      if (isset($e->getError()->param)) {
        error_log("The parameter {$e->getError()->param} is invalid or missing.");
      }
      break;
    default:
      error_log("Another problem occurred, maybe unrelated to Stripe.");
  }
}

http_response_code(200);

お客様のシステムが Webhook イベントにどのように応答するかテストするために、ローカルの Webhook イベントをトリガーすることができます。リンクで設定のステップを完了した後、失敗した支払いをトリガーして、結果のエラーメッセージを表示します。

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

失敗に関する保存された情報を取得する

多くのオブジェクトは、失敗に関する情報を保存します。そのため、何らかの問題が発生している場合は、オブジェクトを取得して詳細を調べることができます。多くの場合、保存された情報はエラーオブジェクトの形式であり、そのタイプを使用して応答を選択することができます。

例:

  1. 特定の支払いインテントを取得します。
  2. last_payment_error が空であるかどうかを判断して、支払いエラーが発生したかどうかを確認します。
  3. エラーが発生していた場合は、タイプと影響を受けたオブジェクトを含めてエラーをログに記録します。
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
<?php
  require 'vendor/autoload.php';

  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%});

  e = payment_intent->last_payment_error
  if isset(e) {
    error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error.")
  }

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

オブジェクト属性値
PaymentIntentlast_payment_errorエラーオブジェクト
SetupIntentlast_setup_errorエラーオブジェクト
Invoice (請求書)last_finalization_errorエラーオブジェクト
SetupAttemptsetup_errorエラーオブジェクト
入金failure_code入金失敗コード
返金failure_reason返金失敗コード

失敗に関する保存情報を使用してコードをテストする場合、失敗した取引のシミュレーションが必要になることがよくあります。大抵の場合、そのためのテストカードまたはテスト用の銀行口座番号を使用できます。以下はその例です。

エラーのタイプと応答

Stripe PHP ライブラリでは、各タイプのエラーはそれぞれのクラスに属します。応答方法については、各クラスのドキュメントをご覧ください。

名前

クラス

説明
支払いエラー

Stripe\Exception\CardException

決済時にエラーが発生して、以下のいずれかの状況が発生しています。
無効なリクエストエラー

Stripe\Exception\InvalidRequestException

API コールのパラメーターが誤っているか、状態が誤っているか、方法が無効でした。

接続エラー

Stripe\Exception\ApiConnectionException

お客様のサーバーと Stripe の間でネットワークの問題が発生しました。
API エラー

Stripe\Exception\ApiErrorException

Stripe 側で問題が発生しました (稀な状況です)。
認証エラー

Stripe\Exception\AuthenticationException

Stripe は、提供された情報では認証できません。
べき等エラー

Stripe\Exception\IdempotencyException

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

Stripe\Exception\PermissionException

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

Stripe\Exception\RateLimitException

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

Stripe\Exception\SignatureVerificationException

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

支払いエラー

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

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

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

Ruby
Python
PHP
Java
Node
Go
.NET
No results
<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
      if ($charge->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_log('Other card error.');
      }
    }
  }

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

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

Ruby
Python
PHP
Java
Node
Go
.NET
No results
<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_log('Other card error.');
      }
    }
  }

テストカードを使用して、一般的な支払いエラーをトリガーすることができます。オプションについては、以下のリストをご覧ください。

以下のテストコードは、いくつかの可能性を示しています。

Ruby
Python
PHP
Java
Node
Go
.NET
No results
example_function([
  'currency' => 'usd',
  'amount' => 2000,
  'confirm' => True,
  'payment_method' => 
'pm_card_radarBlock'
,
]);
console
Ruby
Python
PHP
Java
Node
Go
.NET
No results
Payment blocked for suspected fraud.

支払いが不正使用の疑いのためにブロックされた

タイプ

Stripe\Exception\CardException

コード
$charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
charge->outcome->type == 'blocked'
コード

$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'

問題Stripe の不正使用防止システムである Radar によって支払いがブロックされました

解決方法

このエラーは、組み込みが正常に機能している場合でも発生することがあります。このエラーを検出して、別の支払い方法を使用するように顧客に求めます。

正当な支払いのブロックを減らすには、以下を試します。

Radar for Teams の顧客は、以下の追加のオプションを使用できます。

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

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

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

タイプ

Stripe\Exception\CardException

コード

$e->getError()->code == "card_declined"

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

解決方法

このエラーは、実装が正常に機能している場合でも発生することがあります。これはカード発行会社によるアクションを反映しており、正当なアクションである可能性があります。適切な次のステップを判断するには、拒否コードを使用します。各コードに対する適切な対応については、拒否コードに関するドキュメントをご覧ください。

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

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

他の支払いエラー

タイプ

Stripe\Exception\CardException

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

無効なリクエストエラー

タイプ

Stripe\Exception\InvalidRequestException

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

接続エラー

タイプ

Stripe\Exception\ApiConnectionException

問題お客様のサーバーと Stripe の間でネットワークの問題が発生しました。

解決方法

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

成功したかどうかを確認するには、以下のようにします。

  • 関連オブジェクトを Stripe から取得して、ステータスを確認します。
  • 操作の成功または失敗を示す Webhook 通知をリッスンします。

接続エラーから回復するには、以下を実行できます。

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

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

API エラー

タイプ

Stripe\Exception\APIException

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

解決方法

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

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

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

認証エラー

タイプ

Stripe\Exception\AuthenticationException

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

べき等エラー

タイプ

Stripe\Exception\IdempotencyException

問題別のパラメーターを渡してリクエストを再試行するなど、予期しないものにべき等キーが使用されました。
解決方法
  • べき等キーを使用した後は、同一の API コールでのみ再使用してください。
  • 255 文字の制限内でべき等キーを使用してください。

権限エラー

タイプ

Stripe\Exception\PermissionException

問題このリクエストに使用された API キーには必要な権限がありません。
解決方法
  • アクセスできないサービスに制限付き API キーを使用していないことを確認してください。
  • 権限が不足しているユーザーの役割でログインしているときは、ダッシュボードでアクションを実行しないでください。

レート制限エラー

タイプ

Stripe\Exception\RateLimitException

問題短時間のうちに過剰な回数の API コールが行われました。
解決方法
  • 単一の API コールでこのエラーがトリガーされた場合は、しばらくしてからもう一度お試しください。
  • レート制限を自動的に処理するには、遅延後に API コールを再試行して、エラーが続く場合には遅延時間を飛躍的に増加させます。詳細については、レート制限に関するドキュメントをご覧ください。
  • トラフィックが大幅に増えることが予想され、レート制限の引き上げをご希望の場合は、事前にサポートまでお問い合わせください。

署名確認エラー

タイプ

Stripe\Exception\SignatureVerificationException

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

解決方法

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

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

このページはお役に立ちましたか。
はいいいえ