プロトコル標準

API は一連の HTTP API 標準に従っており、より堅牢な統合を容易にするためにべき等性をサポートしています。

Google がホストする URL

Google がホストする各メソッドのドキュメントには、メソッド名とメジャー バージョン番号を含んだベース URL があります。完全な URL は、呼び出し元の決済インテグレーターのアカウント ID を末尾に追加することによって作成されます。たとえば、Google がホストする echo メソッドのドキュメントには、URL が指定されています。

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo

呼び出し元の決済インテグレーターのアカウント ID が INTEGRATOR_1 の場合、URL の末尾に次の ID を追加します。

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo/INTEGRATOR_1

パートナーがホストする URL

パートナーがホストする各 API メソッドのドキュメントには、メソッド名とメジャー バージョン番号を含んだベース URL があります。ホストする URL に決済インテグレーターのアカウント ID（PIAID）を含めないでください。

サンドボックス環境と本番環境

Google は、サンドボックス環境（開発とテスト用）と本番環境の両方で Chargeback Alert API をホストします。Google サンドボックス環境のリクエストによって、現実世界の金銭的な責任が生じることはありません。サンドボックス環境と本番環境は完全に分離されており、鍵やトランザクション情報は共有されません。

サンドボックスは最初に変更や新機能をテストするために使用されるため、Google ではサンドボックスを常に使用可能にしているものと想定しています。

Google のサンドボックスのベースパス

https://vgw.sandbox.google.com/gsp/

Google の本番環境のベースパス

https://vgw.googleapis.com/gsp/ Iｓ

このガイドでは、本番環境のエンドポイントを使用します。

コンテンツ タイプとエンコード

PGP 暗号化を使用するメッセージ ペイロードは、コンテンツ タイプ application/octet-stream; charset=utf-8 を使用する必要があります。 JWE 暗号化を使用するメッセージ ペイロードでは、コンテンツ タイプ application/jose; charset=utf-8 を使用する必要があります。 rfc4648 §5 で定義されているように、リクエストの本文は base64url エンコードを使用して送信する必要があります。

HTTP ステータス コード

Chargeback Alert API は、サーバーで処理できるすべてのリクエストに対して、HTTP 200 ステータス コードを返すように設計されています。これには、ビジネス ロジックまたはアプリケーション ロジックの観点から成功したリクエストと承認されなかったリクエストの両方が含まれます。リクエストを処理できない場合、これは Google とパートナーとの間のエラーを表すため、HTTP 200 ステータス コードは返されません。代わりに、API レスポンスはオプションの ErrorResponse オブジェクトで以下の適切な HTTP ステータス コードを使用する必要があります。

HTTP エラーと理由
400 BAD REQUEST

クライアントが無効な引数を指定しました。

これは、システムがオペレーションの実行に必要な状態ではないためにオペレーションが却下された場合にも返されることがあります。

これは、システム状態が明示的に修正されるまでリクエストの再試行が成功しない場合に使用します。たとえば、存在しないキャプチャが参照されているために払い戻しリクエストが失敗すると、キャプチャがインテグレーターのシステムに存在するまで再試行は成功しません。
401 UNAUTHORIZED

リクエストにはオペレーションに有効な認証情報がありません。たとえば、無効な署名や不明な署名は 401 を返します。

403 FORBIDDEN / PERMISSION DENIED

呼び出し元には、指定されたオペレーションを実行する権限がありません。

404 NOT FOUND

支払いやユーザーなどリクエストされたエンティティが見つかりませんでした。

409 CONFLICT / ABORTED

オペレーションは、通常、シーケンサー チェックの失敗、取引の中止などの同時実行の問題のために中止されました。

412 PRECONDITION FAILED

このコードは、異なるパラメータでべき等性のキーが再利用されている場合に使用します。

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

一部のシステム リソースがなくなりました。

499 CANCELLED

オペレーションがキャンセルされました（通常は呼び出し元から）。

500 INTERNAL ERROR

内部エラー。このため、基盤となるシステムで想定されている不変性の一部が損なわれていることを意味します。

501 UNIMPLEMENTED

このサービスではオペレーションが実装、サポート、有効化されていません。

503 UNAVAILABLE

サービスは現在使用できません。これは一時的な状態である可能性が高く、再試行すると修正される可能性があります。

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

オペレーションが完了する前に期限が切れました。システムの状態を変更するオペレーションの場合、オペレーションが正常に終了しても、このエラーが返されることがあります。たとえば、サーバーからの正常なレスポンスが期限切れになるほど遅延する場合もあります。

べき等性のリクエスト

べき等性のリクエストは Chargeback Alert API で使用される中心的な戦略で、Google とパートナー間のシステム操作が堅牢でフォールト トレラントになるようにするために使用されます。べき等性のリクエストは、複数回送信される可能性があるリクエストですが、単一のリクエストと同じ効果を持ちます。この戦略では、再試行を安全に行うことで、システム間の結果整合性を促進し、システムがリソースの状態に対する合意を確実に統合できるようにします。

Google の API は、次のような目的でべき等性を利用しています。

  • すべてのアクションを簡単にトレースして監査できるようにすることで、調整に関する問題を減らします。
  • 同じクライアントから同一リクエストが複数回あっても、最終状態が異ならないようにすることで、競合状態を防ぎます。
  • リクエストを独立して理解可能な方法で行うことで状態が最小化され、データ保持によって生じるサーバー負荷を排除することで、パフォーマンスとスループットを向上させることができます。
  • リクエストが再試行であるかどうかを示す追加のフィールドが不要になります。

例

例 1: レスポンスを受信する前に接続が失われた

シナリオ:

  1. Google はインテグレーターにキャプチャ リクエストを送信します。
  2. インテグレーター サーバーがこのリクエストを受け取り、正常に処理されます。
  3. Google のサーバーは、ステップ 2 のレスポンスが届く前に電源を失います。
  4. Google のサーバーが復旧し、同じキャプチャ リクエストが、すべて同じパラメータ（リクエスト ID とリクエストの詳細は同じで requestTimestamp を更新）でインテグレーターのサーバーに送信されます。

結果:

この場合、インテグレーター サーバーはステップ 2 と同じレスポンスで応答する必要があります。これは、responseTimestamp 以外のすべてのパラメータが同じためです。ユーザーの引き落としは、ステップ 2 で 1 回だけ行われます。ステップ 4 がユーザーに金銭的な影響を及ぼすことはありません。

例 2: メンテナンス中のサーバーにリクエストが送信された

シナリオ:

  1. インテグレーター サーバーのデータベースがメンテナンスのため停止しています。
  2. Google がインテグレーターにリクエストを送信します。
  3. インテグレーターが UNAVAILABLE ステータス コードを正しく返します。
  4. Google のサーバーがレスポンスを受信し、再試行のスケジュールを設定します。
  5. インテグレーター サーバーのデータベースがオンラインに戻ります。
  6. Google がステップ 2 からリクエストを再送信します（リクエスト ID とリクエストの詳細は同じで、requestTimestamp を更新）。両方のリクエストのリクエスト ID は同じである必要があります。
  7. インテグレーター サーバーはリクエストを受信し、OK ステータス コードと完全なレスポンスを返します。

結果:

この場合、インテグレーター サーバーはステップ 7 でリクエストを処理する必要があり、HTTP 503（UNAVAILABLE）は返しません。代わりに、インテグレーター サーバーはリクエストを完全に処理し、適切なメッセージで OK を返す必要があります。システムが UNAVAILABLE である間、Google はステップ 2 に似たリクエストを繰り返すことがあります。リクエストごとにステップ 3 のようなメッセージが返されます。最終的には、ステップ 6 とステップ 7 が発生します。

例 3: 復元エラーのため、再試行されたメッセージが最初のメッセージと一致しない

シナリオ:

  1. Google がインテグレーターにリクエストを送信します。
  2. インテグレーター サーバーがこのリクエストを受け取り、正常に処理されます。
  3. Google のサーバーは、ステップ 2 のレスポンスが届く前に電源を失います。
  4. Google のサーバーが復旧し、同じリクエストを送信しようとしていますが、一部のパラメータが異なります。

結果:

この場合、インテグレーター サーバーは、このシステムにエラーがあることを Google に知らせる HTTP 412（PRECONDITION FAILED）エラーコードを返します。