integrate-google-pay

Payroc Google Pay 統合

バージョン確認（最初に実行）

何かを案内したり、フローを開始したりする前に、このスキルが最新であることを確認してください。

1. 上記のフロントマターにある metadata.version フィールドから、このスキルのバージョンを読み取ります。
2. 公開版を取得し、その metadata.version を読み取ります。 https://raw.githubusercontent.com/payroc/skills/main/plugins/payroc/transaction/skills/integrate-google-pay/SKILL.md
3. 2つのバージョンをセマンティックバージョンとして比較します。

   • このバージョン >= 公開版 → メッセージを表示せず、そのまま続行します。（未公開の新しいバージョンを開発者が実行している場合も、問題ありません。）

   • このバージョン < 公開版 → 開発者に次のように伝えます。

     ⚠️ このスキルの新しいバージョン（v<published>）が公開されています。現在実行中のバージョンは v<current> です。最適な結果を得るため、アップグレードをおすすめします。

     現在のバージョンで続行するか、いったん停止して先にアップグレードするかを尋ね、回答に従ってください。

   • 取得できなかった場合（オフライン、ネットワークエラー、404）→ バージョンを確認できなかったことを簡潔に伝え、続行します。

---

初回の呼び出し時に、開発者に次のように案内します。

Payroc Google Pay 統合 加盟店の設定からUATでのテスト取引の成功までご案内します。 ここでは、Google Pay JS APIで決済シートを表示し、Payroc Payments APIで暗号化された決済データを処理する、チェックアウトページでの決済方法としてのGoogle Payを扱います。

PayrocでのGoogle Payの仕組み（4つのステップ）：

1. Google Pay JS APIにPayrocのゲートウェイ情報（ゲートウェイ名とゲートウェイ加盟店ID）を設定します
2. 顧客がGoogle Payボタンをタップすると、Googleが決済シートを表示します
3. 顧客がカードを選択して確定すると、Googleから暗号化された決済データが返されます
4. サーバーで暗号化データを16進数に変換し、Payrocの決済エンドポイントにPOSTします

重要なゲートウェイ情報（出力する前にローカルの説明資料を確認）： PayrocはWorldnetゲートウェイ（Payrocが買収）を通じてGoogle Payを処理します。references/google-pay.md の説明資料には、Google Payの tokenizationSpecification.parameters に設定する具体的な値、つまり gateway（固定値）と gatewayMerchantId（処理端末IDから取得）を記載しています。どちらかを出力する前に references/google-pay.md を読み、記載されている値をそのまま使用してください。記憶を頼りに出力しないでください。

Google PayとHosted Fields／HPPの違い： Google Payは独立した決済フローであり、Hosted Fields JSライブラリもHPPフォームも使用しません。これらの統合を補完するものであり、置き換えるものではありません。

本番環境では登録が必要： Google Payを本番環境で利用するには、Googleに統合を登録する必要があります。UATテストは登録なしで実施できます。

[MCP接続確認ツールが利用可能な場合は、ここで実行し、続行する前に結果を提示してください。]

---

クイックリファレンス

# Identity service (Bearer token — server-side only)
POST https://identity.uat.payroc.com/authorize
x-api-key: <api-key>

# Google Pay JS library (client-side — load in the browser)
https://pay.google.com/gp/p/js/pay.js

# Payments API (server-side — process the hex-encoded Google Pay token)
POST https://api.uat.payroc.com/v1/payments
Authorization:  Bearer <token>
Content-Type:   application/json

# Production base URLs (swap when going live — see Step 4 and Completion)
#   identity.payroc.com/authorize   |   api.payroc.com/v1/payments

正確な値、列挙値のセット、Payroc固有のゲートウェイ定数は、このブロックには含まれていません。各ステップの指示に従って references/ ファイルから確認してください。これはエンドポイントの概要を示すものであり、リファレンスの代わりにはなりません。

---

参考資料

すべての列挙値、スキーマ、Payroc 固有の値は、以下のローカルの references/ ファイルに記載されています。このスキルはそれらを参照して生成し、ライブ検索や記憶には頼りません。互いに補完し合う 3 つの情報源があり、それぞれ異なる種類の質問を担当します。質問に合わない情報源を使うことは、既知の失敗パターンです。

• Payroc API スキーマ（references/api-schema.md）— Payroc API に送信されるすべての情報の信頼できる情報源です。フィールド名、列挙値（channel、paymentMethod.type、paymentMethod.serviceProvider、transactionResult.status など）、必須フィールド、リクエスト／レスポンスの形式が含まれます。Payroc OpenAPI 仕様から必要な部分をまとめたものです。
• Payroc の説明文（references/google-pay.md）— 構成方法と Payroc 固有のゲートウェイ値の信頼できる情報源です。Google Pay JS と Payroc の接続方法、tokenizationSpecification.parameters に設定する値（gateway 定数と gatewayMerchantId の導出方法）、16 進数エンコードの要件が記載されています。
• Google API の仕様に関するメモ（references/third-party/google-request-objects.md および references/third-party/google-client.md）— Google Pay JS API の形式に関する信頼できる情報源です。PaymentDataRequest、tokenizationSpecification、サポート対象のネットワーク／認証方式、PaymentsClient のメソッド（isReadyToPay、loadPaymentData、createButton）、paymentData コールバックの形式が記載されています。Google が文書化した API 仕様を、独自の言葉でまとめたメモです。プロパティ名、使用できる子キー、PaymentsClient のメソッド名を確認する必要がある場合は、必ず参照してください。

「Payroc の支払いリクエスト本文はどのような形式ですか？」という質問なら、references/api-schema.md を参照してください。「gateway には何を設定すべきで、gatewayMerchantId はどのように導出しますか？」という質問なら、references/google-pay.md を参照してください。「PaymentDataRequest の正確な形式と、その中での tokenizationSpecification の配置場所は？」という質問なら、references/third-party/ にある Google のメモを参照してください。tokenizationSpecification.parameters の値は Payroc が定め、周囲のコンテナは Google が定めています。

情報源	ローカルファイル	用途
Payroc API スキーマ	references/api-schema.md	Payroc API のフィールド名、列挙値、リクエスト／レスポンスの形式
エラーレスポンス形式	references/error-response-format.md	エラーエンベロープ（RFC 7807）＋ Payroc の errors[] ＋標準エラータイプカタログ
Google Pay をインテグレーションに追加する（Payroc の説明）	references/google-pay.md	Payroc との構成方法＋標準の gateway 値＋gatewayMerchantId の導出方法
Google — リクエストオブジェクト	references/third-party/google-request-objects.md	PaymentDataRequest、tokenizationSpecification、サポート対象ネットワーク、JS オブジェクトの形式
Google — クライアント	references/third-party/google-client.md	PaymentsClient コンストラクター、isReadyToPay、loadPaymentData、createButton、コールバックの形式

これらはこのスキルで使用するローカルのスナップショットであり、信頼できる情報源です。参照元の URL と最終同期日は references/_sources.md に記録されています。内容が古いと思われる場合は、そこから再生成してください。

---

基本原則

1. 質問する前に調査する — 何かを尋ねる前にコードベースを読み、見つかった情報を活用して自明な質問を省き、的を絞った質問をします。
2. コーディングする前に質問する — 実装コードを書く前に、質問を通じて不明点を解消します。
3. 次に進む前に検証する — 開発者が現在のステップのチェックポイントが UAT で合格したと確認するまで、次のステップに進みません。
4. 推測せず、参照資料を読み、質問に合った資料を選ぶ。 この統合には、2つではなく 3つ の情報源があります。質問に合わない資料を使うと、記憶にあるものの誤った値が紛れ込むことになります。
   • Payroc API のスキーマ、フィールド名、列挙値、必須フィールド → references/api-schema.md。 Payroc の API に送信されるものはすべて対象です。特定の文字列を受け付けるフィールド値（channel、paymentMethod.type、paymentMethod.serviceProvider、通貨、国、その他の列挙型パラメーター）は、トレーニングデータではなくスキーマの参照資料から取得します。もっともらしい文字列でも、参照資料に記載されていなければ API エラーの原因になります。
   • 構成、Payroc 固有のゲートウェイ値（gateway、gatewayMerchantId の導出）、16進数エンコード要件 → references/google-pay.md。 「Payroc が求める gateway 定数は何か」「gatewayMerchantId はどのように導出するか」は、スキーマや Google に関する質問ではなく、説明文に関する質問です。
   • Google Pay JS API の構造、PaymentDataRequest、tokenizationSpecification、対応ネットワーク、PaymentsClient のメソッド → references/third-party/ 配下の Google のメモ。 Payroc の説明文ではこれらを名前で参照していますが、Google の正確なプロパティパス、子キーの表記、メソッドシグネチャについては信頼できる情報源ではありません。JS API の仕様を確認する必要がある場合は、Google のメモを読みます。
   • 情報源を混同しない。 channel は Payroc の支払いリクエストに属するもので（列挙値は references/api-schema.md に記載）、Google Pay のリクエストには属しません。Google の対応ネットワーク定数（例："VISA"、"MASTERCARD"）は Google のメモに記載され、PaymentDataRequest に属するもので、Payroc の支払いリクエストには属しません。それぞれの値に適した参照資料を読みます。
5. 値ごとに読み、出力する。 列挙値（Payroc：channel、paymentMethod.type、paymentMethod.serviceProvider、通貨、国、transactionResult.status。Google：決済ネットワーク、認証方式、環境）、PaymentDataRequest のプロパティパス、PaymentsClient.* のメソッド呼び出し、または Payroc の gateway 定数や gatewayMerchantId の導出を出力する前に、該当するローカルの参照資料を読みます。Payroc の説明文（references/google-pay.md）には gateway 定数と gatewayMerchantId の導出が記載され、references/api-schema.md には Payroc REST の列挙値が記載され、Google のメモには JS API の仕様が記載されています。これらを記憶から出力せず、それぞれの情報源から確認します。
6. 認証情報をハードコードしない — API キーと端末 ID は、ソースコードではなく環境変数またはシークレットマネージャーから取得します。
7. 先に診断する — ステップが失敗した場合は一時停止し、続行する前にエラー分類に沿って原因を確認します。

---

インテーク

まず、コードベースを確認します。 以下を調べてください。

• サーバー側の言語とフレームワーク
• 既存のチェックアウトまたは決済関連のルートやハンドラー
• 既存のPayroc連携（HFまたはHPP）の有無 — APIキーとターミナルIDがすでに設定されている可能性があります
• 環境変数や設定の管理方法
• Google Pay JSやGoogle Payの加盟店IDがすでに設定されているかどうか

すでに推測できる情報を尋ねずに済むよう、確認した内容を活用してください。

次に、まだ必要な情報を尋ねます。最低限、以下を確認してください。

質問1 — Google Payは適切な決済方法ですか。また、既存連携への追加ですか、それとも単独での構築ですか？

	Google Pay（このスキル）	Hosted Fields	Hosted Pages（HPP）
顧客の利用方法	Google Payボタンをタップし、保存済みのGoogleウォレットのカードで決済します — カード情報の入力は不要です	Payrocのウィジェットが埋め込まれた独自のフォームにカード情報を入力します	Payrocがホストするページにリダイレクトされて決済し、その後サイトに戻ります
カードデータの保存場所	Googleのウォレットです。サーバーが受け取るのは暗号化されたトークンです	ページ内のPayrocウィジェットです	Payrocがホストするページです
対応状況	最新のブラウザーであれば対応しています — Chrome、Edge、Firefox、iOS版Chromeに対応し、Safariには対応していません（Safariでは代わりにApple Payを使用します）	すべての最新ブラウザーに対応しています	すべての最新ブラウザーに対応しています
このスキル	✓ このスキルで扱います	別のスキルです	別のスキルです

Google Payはカード入力方式を補完するものであり、置き換えるものではありません — ほとんどの連携では、Hosted FieldsまたはHPPと併用します。また、Androidに限定されません。iOSユーザーも、Androidユーザーと同じようにChromeでGoogle Payを使用できます。重要なのはデバイスではなくブラウザーです — どのデバイスでもSafariはGoogle Payに対応していません。この点を明確にしたうえで、既存連携への追加か単独での構築かを確認してください。

• 既存のPayroc連携（HFまたはHPP）にGoogle Payを追加する場合 → APIキーとターミナルIDはすでに設定されている可能性が高いため、Google Pay固有の手順に重点を置きます
• 新規連携でGoogle Payのみを使用する場合 → 認証情報の設定を含め、最初から始めます

開発者の回答を待ってから続行してください。

---

前提条件

これらはGoogle Payの実行とテストに必要なものであり、コードの作成に必要なものではありません。開発者がすでに用意している場合は問題ありません。まだ用意できていなくても、作業を止めないでください。各値を環境変数から読み込むようにコードを実装し、そのまま開発を続けてください。テスト前に、開発者が実際の値を用意できます。

1. APIキー — PayrocのアイデンティティサービスからBearerトークンを取得するために使用します。Hosted Fieldsで使用するものと同じ認証情報で、Payroc Integrationsチームが発行します。
2. 決済処理ターミナルID — Payroc Integrationsチームが発行するUATターミナルIDです。gatewayMerchantId（ターミナルIDの末尾3文字を除いた値）の導出にも使用します。
3. Google Merchant ID — UATではテスト値を使用できるため、開発の妨げにはなりません。本番環境用の値はGoogleへの登録後に取得します（ステップ4を参照）。コードからはGOOGLE_MERCHANT_IDのような変数を読み込めます。

不足しているものがある場合は、警告しますが作業は止めません。 コードベースに既存の環境変数の命名規則がないか調べ、あればそれに合わせてください。ない場合は、PAYROC_API_KEY、PAYROC_TERMINAL_ID、GOOGLE_MERCHANT_IDのような名前を提案します。これらの値を環境変数から読み込むコードを作成し、その後、開発者に次のようにはっきり伝えてください。

⚠️ APIキー、ターミナルID、Google Merchant IDを<VAR names>から読み込むように実装しました。UATで実行またはテストするには、PayrocのUATターミナルとAPIキーが必要です（Payroc Integrationsチームにお問い合わせください）。UATではテスト用のGoogle Merchant IDで問題ありませんが、本番環境では実際のGoogle Merchant ID（Google Pay Business Consoleから取得）が必要です（ステップ4）。その間も開発を続けられます。

不足しているものの入手を手伝えることを伝え、開発者が希望する場合は開発を続けてください。

チェックポイント

認証情報が確認済みであるか、開発者が不足しているものとその入手方法、コードが読み込む環境変数を把握したうえで、作業を進めることを選んでいる状態です。不足項目を明示しないままにしてはいけませんが、それを理由に作業を止めてはいけません。

---

ステップ1 — 認証：Bearerトークンを取得する

references/identity-call.mdを読みます — 正式なBearerトークン交換リファレンスです。アイデンティティエンドポイントのURL、ヘッダー名、レスポンスの形式を推測してはいけません。このファイルに記載された内容だけを出力してください。 references/google-pay.mdを読みます — Payrocの説明資料です。Google PayのフローにおけるBearer認証の位置付けを確認します。

何かを記述する前に、両方を読んでください。リファレンスから、次の項目を確認します。

• アイデンティティサービスのエンドポイント
• 必須ヘッダーとその形式
• アクセストークンを含むレスポンスフィールド

APIキーを使ってアイデンティティサービスにPOSTし、アクセストークンを返すサーバー側の関数を実装します。これはサーバー側で実行する必要があります — APIキーをブラウザーに送ってはいけません。

チェックポイント

呼び出しはaccess_tokenを含む200レスポンスを返しますか？

---

ステップ2 — Google Pay JSを設定して読み込む

このステップでは2つの情報源を参照します — PaymentDataRequestの形式とPaymentsClient APIはGoogleが管理し、tokenizationSpecification.parametersに指定する値はPayrocが管理します。何かを記述する前に、両方を読んでください。

• references/third-party/google-request-objects.mdを読む — 正確なプロパティパス（allowedPaymentMethods、tokenizationSpecification、merchantInfo、transactionInfo）、サポートされるネットワーク定数の綴り、認証方式の定数を確認します。
• references/third-party/google-client.mdを読む — PaymentsClient、isReadyToPay、loadPaymentData、createButtonと、それらの引数および戻り値の形式を確認します。
• references/google-pay.mdを読む — gateway定数、gatewayMerchantIdの導出方法、tokenizationSpecification.parametersに指定するその他のPayroc固有の値を確認します。

PaymentDataRequest または PaymentsClient.* の呼び出しを出力する前に — Google のノートを確認してください

1. 読むもの。 上記の Google のノート（request-objects と client）の両方です。トレーニングデータをもとに API を言い換えないでください。
2. 確認すること。
   • PaymentDataRequest の正確なプロパティ階層と、その中での tokenizationSpecification の位置。
   • サポート対象ネットワークの定数（Google では "VISA"／"MASTERCARD" を使用します。大文字・小文字も確認してください）。
   • PaymentsClient のコンストラクター引数、isReadyToPay の引数、loadPaymentData の戻り値の正確な形式。
3. 確認してから出力すること。 PaymentDataRequest のすべてのプロパティを、Google のノートに記載されたパスに配置してください。各 PaymentsClient.* 呼び出しは、ドキュメントに記載されたインターフェイスに従ってください。存在すると想定したメソッドやプロパティが Google のノートに記載されていない場合は、別の名前を作って再度試さず、ソース（references/_sources.md を参照）から導き直してください。

gateway と gatewayMerchantId を出力する前に — Payroc の説明文を確認してください

これらは Google の値ではなく、Payroc 固有の値です。tokenizationSpecification.parameters の中に記載されています。正確な情報源は references/google-pay.md です。

1. 読むもの。 references/google-pay.md の tokenizationSpecification の設定を説明しているセクション（説明文のステップ 1「Google Pay API との統合」）。
2. 確認すること。
   • 説明文に記載された gateway 定数の正確な値。
   • gatewayMerchantId の正確な導出ルール。説明文に導出方法が明記されていない場合は、推測せずにエスカレーションしてください。
3. 確認してから出力すること。 説明文に記載された値をそのまま使用してください。記憶している値に置き換えないでください。

上記の参照資料を読んでから、クライアント側の統合を実装してください。

1. Google Pay の JS ライブラリを読み込みます：https://pay.google.com/gp/p/js/pay.js
2. 適切な環境（UAT では TEST、本番環境では PRODUCTION）を指定して PaymentsClient を作成します。環境定数は Google の client ノートで確認してください。
3. ボタンを表示する前に、Google の client ノートに従って、サポート対象の決済方法を指定し、準備状態確認メソッド（isReadyToPay）を呼び出します。
4. 準備状態の確認結果が true の場合に限り、Google の client ノートに従って createButton で Google Pay ボタンを表示します。
5. ボタンがクリックされたら、完全な PaymentDataRequest を指定して loadPaymentData を呼び出します。
6. 成功したら、paymentData をサーバーに送信します（ステップ 3）。

Google Pay JS の既知の形式に関する失敗パターン

症状を見分けるための一覧です。修正方法は常に、関連するローカルの参照資料を読み、そこに記載された内容を出力することです。「以下の値を使う」ことではありません。

• 症状： loadPaymentData が、トークン化仕様の問題を示す OR_BIBED_* などの Google 側エラーで拒否される。過去の誤り： gateway／gatewayMerchantId を tokenizationSpecification.parameters の外側に配置した、または Google のノートではなくトレーニングデータからパスを推測した。確認先： tokenizationSpecification の正確なネストを確認するには、references/third-party/google-request-objects.md を参照してください。
• 症状： Payroc の決済呼び出しで、ゲートウェイトークン化されたデータが拒否される。過去の誤り： Google のノートではなくトレーニングデータから gateway 定数または gatewayMerchantId の導出方法を取得した。確認先： この 2 つの値の正確な情報源として、references/google-pay.md を参照してください。
• 症状： PaymentsClient メソッドの TypeError、または想定外の戻り値形式が発生する。過去の誤り： 引数や戻り値の形式を推測した。確認先： references/third-party/google-client.md を参照してください。

チェックポイント

Google Pay ボタンはページに表示されていますか？クリックすると決済シートが表示されますか？

---

ステップ 3 — 決済を処理する

このステップでは2 つの情報源を参照します。暗号化トークンの形式は Google が定義し、/v1/payments に POST するリクエストのラップ形式と enum 値は Payroc が定義しています。両方を確認してください。

• Google — paymentData コールバックの形式： 暗号化トークンが paymentData 内のどこにあるか（例：paymentData.paymentMethodData.tokenizationData.token）を確認してください。トレーニングデータではなく、references/third-party/google-request-objects.md を参照してください。
• Payroc の説明とスキーマ： リクエストの組み立て方は references/google-pay.md を、正確なフィールド名と enum 値は references/api-schema.md の paymentRequest と paymentMethod の digitalWallet バリアントを参照してください。

トレーニングで得た知識をもとに、フィールド名、エンドポイント URL、暗号化データ形式を使用しないでください。 情報源は別々です。Google は paymentData の構造（references/third-party/）を、Payroc は references/api-schema.md のリクエスト本文の形式を定義しています。コードを出力する前に両方を確認してください。

loadPaymentData が解決すると、paymentData オブジェクトに暗号化された決済情報が含まれます。サーバーでは次の処理が必要です。

1. paymentData から暗号化された決済トークンを抽出します（正確なパスは Google の request-objects の説明で確認してください）。
2. 16 進数形式に変換します（正確な要件は references/google-pay.md で確認してください。明記されていない場合は、references/api-schema.md で encryptedData フィールドに記載された形式上の制約を確認してください）。
3. Payroc の決済エンドポイントに POST します。リクエストの構造は通常、次のようになります（references/api-schema.md で確認してください）。
   • paymentMethod.type — references/api-schema.md の paymentMethod.type enum で、デジタルウォレットに現在使用されている値を確認してください。記憶を頼りに "digitalWallet" と決めつけないでください。
   • paymentMethod.serviceProvider — references/api-schema.md で Google Pay に現在使用されている enum 値を確認してください。記憶を頼りに "google" と決めつけないでください。
   • paymentMethod.encryptedData — 手順 2 で 16 進数にエンコードしたトークンです。
   • 標準の channel、processingTerminalId、order フィールドも含めます（すべて確認してから出力してください。下記の enum に関する注意事項を参照してください）。
4. HTTP 201 の場合は、レスポンス本文を確認したうえで（下記の成功分岐に関する注意事項を参照）、クライアントに成功を返し、確認メッセージを表示します。
5. エラーが発生した場合は、クライアントにエラーを伝えます。

references/api-schema.md で Payroc の channel enum を確認してください。 channel は Payroc の決済リクエストのフィールドであり、Google Pay のリクエストにはありません。過去に発生した既知の失敗（関連する他のインテグレーションから）： あるモデルが、ブラウザー内でのチェックアウトなら妥当そうに見えるという理由で channel: "internet" を出力したところ、Payroc はエラー詳細に enum の値一覧を含む HTTP 400 を返しました。ここで正しい値を暗記するのではなく、本文を組み立てる際にスキーマリファレンスの paymentRequest.channel を確認してください。もっともらしい類似の値（internet、online、ecommerce、card-not-present）を使うのが、この失敗のよくあるパターンです。

推測した transactionResult.status の一部だけで判断せず、responseCode で決済の成功を判定してください。 references/api-schema.md を参照してください。承認を示すのは responseCode === 'A' です（成功レスポンスには approvalCode と OK の responseMessage も含まれます）。transactionResult.status はライフサイクルの状態です。A の場合、ready（キューに登録済み／キャプチャ済み）と pending（承認済み、キャプチャ待ち — 例：事前承認または autoCapture: false）は、どちらも承認成功を示します。declined／expired などは成功ではありません。過去に発生した既知の失敗（関連する他のインテグレーションとベンチマークから）： あるモデルが APPROVAL_STATUSES のリストを作成し、その一部（例：pending）を漏らしたため、実際には承認されている決済をエラーとして扱いました。状態の集合を記憶から列挙しないでください。成功分岐は responseCode === 'A' を基準とし、status はライフサイクルの判定に使用してください。E（保留）と P（一部承認）は意図をもって処理し、D／R／C は拒否として扱ってください。

チェックポイント

決済 API は UAT で HTTP 201 を返しますか？チェックアウトページに決済確認が表示されますか？

---

ステップ 4 — Google に登録する（本番環境のみ）

本番運用を開始する前に、統合を Google に登録する必要があります。

1. Google Pay Business Console で登録します
2. Google から本番用の merchantId が割り当てられます
3. PaymentsClient の環境を TEST から PRODUCTION に切り替えます
4. Payroc Integrations チーム（[email protected]）に連絡し、端末で Google Pay の本番処理が有効になっていることを確認します

この手順は UAT テストでは不要です。

---

ローカルテストの方針

Google Pay はクライアントとサーバーの両方で完結するため、インバウンド Webhook はありません。そのため、HPP とは異なり、公開 URL に到達できる必要はなく、トンネル（ngrok、Dev Tunnels など）も不要です。

• Google Pay ボタンを使用するには、セキュアコンテキストが必要です。ブラウザーは http://localhost をセキュアとして扱うため、HTTPS なしでローカル開発できます。それ以外のホストでは、ボタンを表示するために HTTPS で配信する必要があります。
• UAT では、PaymentsClient に TEST 環境を使用します。Google は Payroc の UAT 端末で受け入れられるテスト決済データを返します。TEST でテストする場合、Google Business Console への登録は不要です。
• 本番環境では、Business Console への登録（ステップ 4）に加えて、本番用のベース URL と PRODUCTION 環境が必要ですが、ドメインごとの検証ファイルは不要です（これは Google Pay ではなく、Apple Pay に関するものです）。

---

エラーの分類

症状	考えられる原因	修正方法
Google Pay ボタンが表示されない	isReadyToPay が false を返した	サポートされているネットワークと認証方法が、テスト環境で許可されている内容と一致しているか確認します。TEST 環境では、どのデバイスでも動作するはずです
loadPaymentData が例外をスローする、または拒否される	PaymentDataRequest の設定ミス	ブラウザーのコンソールで Google Pay のエラー詳細を確認します。gateway、gatewayMerchantId、merchantId の各フィールドがドキュメントの要件と一致していることを確認します
決済シートは表示されるが、確認時に失敗する	gatewayMerchantId が正しくない	算出方法を確認します。ターミナル ID の末尾 3 文字を除きます。数式を確認するには references/google-pay.md を読みます
決済 API が 401 を返す	Bearer トークンの期限切れ、または API キーの誤り	Bearer トークンを再取得します。x-api-key の値を確認します
決済 API が 400 を返す	encryptedData が 16 進数形式ではない、または必須フィールドが不足している	references/google-pay.md／references/api-schema.md で encryptedData の形式要件を再確認し、16 進数への変換ロジックを確認します
決済 API は処理されるが、結果が想定と異なる	serviceProvider の値が誤っている	"google"（小文字）である必要があります。大文字と小文字の誤りがないか確認します
TEST では本番用ボタンが動作するが、PRODUCTION では動作しない	Google への登録が済んでいない、または本番処理が有効になっていない	Google Pay Business Console への登録を完了し、Payroc Integrations チームに連絡します
Payments API が、エラー詳細で "channel"（または別の列挙型フィールド）を示し、許容値の一覧とともに HTTP 400 を返す	列挙型以外の値が送信された（過去に関連する統合で発生した例：channel: "internet"、"online"、"ecommerce"）。スキーマ値の代わりに、もっともらしい類似値が使われた	references/api-schema.md の paymentRequest.channel（または該当フィールド）を読み、一覧にある値のいずれかを送信します。英語としてもっともらしいという理由で列挙型の値を推測しないでください
Payroc API が paymentMethod.type または paymentMethod.serviceProvider を拒否する	references/api-schema.md を読まず、トレーニングデータで記憶した digitalWallet／google の値をスキルが送信した	references/api-schema.md から現在の paymentMethod.type と paymentMethod.serviceProvider の列挙値を読み、一覧にある値を送信します。記憶していた値がたまたま正しくても、参照ドキュメントを読まなかったこと自体が不具合です
Google 側のエラー（OR_BIBED_* など）に tokenizationSpecification の問題が記載され、PaymentDataRequest が拒否される	gateway／gatewayMerchantId の配置または値をトレーニングデータから取得した、あるいはリクエスト内の誤ったパスに tokenizationSpecification をネストした	正確なネスト方法については references/third-party/google-request-objects.md を読み、gateway 定数と gatewayMerchantId の算出方法については references/google-pay.md を読みます。両方のソースを参照する必要があります。どちらか一方だけでは不十分です
PaymentsClient のメソッドで TypeError が発生する、または予期しない形式が返される	Google クライアントのメモではなく、トレーニングデータからコンストラクターの引数形式、メソッド名、またはコールバックの形式を取得した	references/third-party/google-client.md を読みます。コンストラクターと、呼び出すすべてのメソッドを確認します。作り出したり名前を変更したりしないでください。想定した名前が Google のメモにない場合は、ソースから改めて確認します（references/_sources.md を参照）
アプリでは決済失敗と記録されたが、銀行は実際には承認していた。Payroc のレスポンスには responseCode: "A" と approvalCode／OK メッセージが表示される	推測した transactionResult.status の一部だけを対象に成功判定していた（過去の失敗例：pending などの承認済み状態を含まない APPROVAL_STATUSES リストを使い、実際の承認がひそかに失敗扱いになった）	references/api-schema.md に従い、responseCode === 'A' を成功判定の条件にします。ready と pending は承認済みとして扱い、status はライフサイクルのみを示すものとして扱います。承認ステータスの一覧を記憶から列挙しないでください

---

検証チェックリスト

• API キーとターミナル ID は環境変数から取得されており、ソースコードに含まれていない
• Bearer トークンはサーバー側で生成され、ブラウザーに公開されていない
• gateway 定数と gatewayMerchantId の導出方法は、記憶に頼らず references/google-pay.md で確認されており、値は説明文と一致している
• PaymentDataRequest の構造と PaymentsClient.* の呼び出しは、references/third-party/ 配下の Google の資料と照合されている
• Payroc API のすべての列挙値（channel、paymentMethod.type、paymentMethod.serviceProvider など）は、references/api-schema.md で確認されている
• サーバー側の成功分岐では responseCode === 'A' をキーとしている（references/api-schema.md に準拠）。ready と pending を承認済みとして扱い、D／R／C は拒否として扱っている。推測した transactionResult.status の一部だけに依存していない
• Google Pay ボタンは isReadyToPay が true を返した場合にのみ表示される
• Payroc API に送信する前に、暗号化された決済データを 16 進形式に変換している
• テスト用 Google Pay 取引で、UAT において決済 API が HTTP 201 を返す
• （本番環境）Google Pay Business Console への登録が完了し、merchantId が更新されている
• （本番環境）Payroc Integrations チームが本番処理の有効化を確認している

---

アンチパターン

説明文を参照せず、記憶に頼って gateway 定数や gatewayMerchantId の導出方法を出力すること。 値は references/google-pay.md にあります。どちらの値も出力する前に、必ずこのファイルを読んでください。記憶に頼って出力しないでください。過去の失敗例として、gateway 定数の大文字・小文字の誤りや、導出方法の間違い（例：誤った文字数を削除する）があり、いずれも認証やルーティングの失敗につながります。

tokenizationSpecification.parameters の正しい情報源を記憶だと考えること。 tokenizationSpecification.parameters 内の値は Payroc 固有で、references/google-pay.md に記載されています。tokenizationSpecification の周囲の構造（PaymentDataRequest 内での配置場所）は Google 固有で、references/third-party/google-request-objects.md に記載されています。両方を読む必要があり、どちらか一方だけでは不十分です。

Google Pay ボタンを無条件に表示すること — 必ず isReadyToPay の結果で制御してください。利用できないボタンを表示すると、クリック時にエラーが発生します。

paymentData オブジェクト全体を 16 進エンコードすること — 16 進エンコードするのは、paymentData 内の暗号化された決済トークンだけです。references/third-party/google-request-objects.md で対象フィールドを正確に確認してください。

本番稼働前に Google への登録を省略すること — TEST 環境では登録なしで動作しますが、本番環境で処理を行うには、Business Console への登録を完了し、Payroc に連絡する必要があります。

---

完了

HTTP 201 が確認でき、チェックリストのすべての項目に合格したら：

インテグレーションが完了しました。 構築した内容は次のとおりです：

• Google Pay ボタン — 条件付きで表示され、クリックすると Google Pay の決済シートが表示されます。
• ゲートウェイ設定 — gateway 定数と gatewayMerchantId の値は Payroc の Google Pay 説明文から確認されており、Payroc 経由でリクエストをルーティングします。
• 決済処理 — 暗号化された決済データを 16 進エンコードし、Payroc の決済エンドポイントに POST します。
• UAT で検証済み — Google Pay のエンドツーエンド取引が確認されています。

本番稼働の前に： Google Pay Business Console への登録を完了し、merchantId を本番環境の値に更新し、PaymentsClient を PRODUCTION 環境に切り替え、UAT の決済 API URL を本番環境の URL に置き換え、Payroc Integrations チームに本番処理が有効になっていることを確認してください。

次のステップを提案します：

• Apple Pay — Safari（iOS または macOS）を利用する顧客向けに Apple Pay を追加します。Google Pay が対応できない Safari ユーザーをカバーできます。Apple Pay は Apple Pay JS API を使用し、ドメインの検証が必要です。これは別のスキルで扱います。
• Hosted Fields — 開発者がカード入力フォームの代替手段も必要とする場合は、Hosted Fields スキルを利用します。