integrate-apple-pay

Payroc Apple Pay 統合

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

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

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

   • 現在のバージョン >= 公開バージョン → メッセージを出さずに続行します。（未リリースの新しいバージョンを開発者が実行している場合も問題ありません。）

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

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

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

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

---

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

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

Payroc での Apple Pay の仕組み（4 つの部分）：

1. Self-Care Portal でドメインを Apple に検証してもらい、ドメイン ID を取得します
2. 顧客が Apple Pay ボタンをタップすると、Apple Pay JS API が onvalidatemerchant イベントを発生させます。サーバーは Payroc API を呼び出してセッションを開始し、レスポンスを Apple に返します。エンドポイントには、新しい POST /v1/payments/apple-pay/sessions（新規統合ではこちらを推奨）と、従来の POST /v1/processing-terminals/{processingTerminalId}/apple-pay-sessions の2種類があります。
3. Apple が支払いシートを表示し、顧客は Face ID / Touch ID で承認します
4. onpaymentauthorized イベントが暗号化された支払いデータとともに発生します。サーバーはこれを 16 進数に変換し、Payroc の支払いエンドポイントに POST します

重要： Apple Pay は Apple デバイス（iPhone、iPad、Mac）でのみ動作し、Safari または WebKit ベースのブラウザーが必要です。必ず ApplePaySession.canMakePayments() を使用して、条件に応じて Apple Pay ボタンを表示してください。

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

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

---

クイックリファレンス

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

# Apple Pay JS API — provided by Safari / WebKit; there is no script tag to load

# Apple Pay session start — payments-path variant (PREFERRED for new integrations)
# processingTerminalId is a body field; no path parameter needed
POST https://api.uat.payroc.com/v1/payments/apple-pay/sessions
Authorization:  Bearer <token>
Content-Type:   application/json

# Apple Pay session start — terminal-path variant (original; still supported)
POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/apple-pay-sessions
Authorization:  Bearer <token>
Content-Type:   application/json

# Payments API (server-side — process the hex-encoded Apple 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 Completion)
#   identity.payroc.com/authorize   |   api.payroc.com/v1/...

正確な値、列挙型の値、およびリクエスト／レスポンスの形式は、このブロックには記載されていません。各ステップの指示に従って references/ ファイルから読み取ってください。これはエンドポイントの概要をすぐに確認するためのものであり、リファレンスの代わりにはなりません。

---

参考資料

列挙値、スキーマ、Apple Pay JS API の全容は、以下のローカルファイル references/ にあります。このスキルはライブ検索や記憶ではなく、これらの情報をもとに応答します。それぞれ異なる種類の質問に対応しており、質問に合わない情報源を使うのは、既知の失敗パターンです。

• references/api-schema.md — Payroc API に送信する値や構造の信頼できる情報源です。 フィールド名、列挙値、必須フィールド、リクエストとレスポンスのスキーマ（セッション開始と決済のリクエスト）を確認できます。Payroc API のフィールド名や、そのフィールドで受け付けられる値を確認するときは、必ずこのファイルを参照してください。このスキルにおける正式な情報源です。
• Payroc の解説ガイド（ローカルコピー） — アプローチの信頼できる情報源です。 呼び出しの順序、Apple Pay フローと Payroc のセッション開始および決済エンドポイントの組み合わせ方、エンドツーエンドの全体像を確認できます。統合の組み立て方を学ぶときに使用してください。
• Apple の派生ノート（ローカルの references/third-party/ 以下） — Apple Pay JS API の信頼できる情報源です。 ApplePaySession コンストラクター、イベント名（onvalidatemerchant、onpaymentauthorized、oncancel）、メソッド（canMakePayments、completeMerchantValidation、completePayment）、ステータス定数、Apple Pay の支払いトークン形式は、すべて Payroc ではなく Apple が定めています。これらのノートには、事実に基づく API の全容が独自の言葉でまとめられています。Payroc の解説ガイドには、これらが Payroc のエンドポイントとどのように連携するかが記載されていますが、Apple 側の仕様そのものを確認するための正式な情報源ではありません。

「Payroc のセッション開始リクエストや決済リクエストをどう構成するか」という質問なら、references/api-schema.md を参照してください。「どの順番で呼び出すか」という質問なら、Payroc の解説コピーを参照してください。「ApplePaySession のコンストラクターシグネチャは何か」「顧客が承認したときに発火するイベントは何か」という質問なら、Apple の派生ノートを参照してください。Payroc が所有するのは復号エンドポイントと Apple の支払いトークンを包むラッパーであり、ブラウザー側の支払いシートはすべて Apple が所有します。

情報源	ローカルファイル	用途
API スキーマのリファレンス	references/api-schema.md	Payroc のすべての列挙値、必須フィールド、リクエスト／レスポンスのスキーマ（2 種類のセッション開始方式と決済）。新しい統合で推奨される決済経路のエンドポイント POST /v1/payments/apple-pay/sessions と、従来のターミナル経路のエンドポイント POST /v1/processing-terminals/{processingTerminalId}/apple-pay-sessions を含みます。
エラーレスポンス形式	references/error-response-format.md	エラーエンベロープ（RFC 7807）、Payroc の errors[]、正規のエラータイプカタログ
加盟店向け Apple Pay の設定（Payroc の解説）	references/set-up-apple-pay-for-a-merchant.md	ドメイン検証／セルフケアポータルの設定、ドメイン ID の取得
統合への Apple Pay の追加（Payroc の解説）	references/add-apple-pay-to-your-integration.md	ベアラートークン、セッション開始の呼び出し、売上処理の組み立て
Apple — ApplePaySession（派生ノート）	references/third-party/apple-applepaysession.md	JS API のコンストラクター、イベント／メソッド名、ステータス定数
Apple — Apple Pay ボタン（派生ノート）	references/third-party/apple-pay-button.md	ボタンの表示方法（CSS と Web コンポーネント＋SDK スクリプト）および正しい表示条件
Apple — 支払いトークン形式（派生ノート）	references/third-party/apple-payment-token.md	Payroc 向けに 16 進数エンコードするトークンの JSON フィールド名
Apple — サーバー／加盟店検証の設定（派生ノート）	references/third-party/apple-server-setup.md	加盟店検証フローに関する情報、ドメイン関連付けファイル

これらはこのスキル向けのローカルスナップショットであり、信頼できる情報源です。参照元 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 エラーになります。
   • アプローチ、手順、Apple Pay と Payroc の連携方法 → Payroc の説明資料。 「どの呼び出しが先ですか？」や「セッション開始時の本文で Payroc が求めるものは何ですか？」といった質問には、ガイドが役立ちます。
   • Apple Pay JS API の構造、イベント名、メソッド名 → references/third-party/ にある Apple の派生ノート。 ApplePaySession、そのコンストラクターのシグネチャ、イベントハンドラー（onvalidatemerchant、onpaymentauthorized、oncancel）、メソッド（canMakePayments、completeMerchantValidation、completePayment）、ステータス定数は、すべて Apple が定義するものです。Payroc の説明ガイドでもこれらに触れていますが、構造を確認するための正式な情報源ではありません。JS API の仕様について確認が必要な場合は、Apple の派生ノートを読んでください。
   • リクエストとレスポンスのスキーマは異なります。両方を確認してください。 Payroc のレスポンスが Payroc のリクエストと同じ構造だと決めつけず、references/api-schema.md でそれぞれ確認してください。
   • 情報を混同しないでください。 channel は Payroc の決済リクエストにあり、Apple Pay のセッションオブジェクトにはありません。Apple の決済ネットワーク定数（例："visa"、"masterCard"）は Apple の派生ノートに記載されており、ApplePaySession のリクエストに使います。Payroc の決済リクエストには使いません。それぞれの値に適したリファレンスを読んでください。
5. 値ごとに、読んでから出力する。 列挙値（Payroc の channel、paymentMethod.type、paymentMethod.serviceProvider、通貨、Apple の決済ネットワーク、加盟店機能、ステータス定数）、ApplePaySession のコンストラクターオプション、Apple Pay JS API のイベント名やメソッド名を出力する前に、該当するローカルリファレンスから確認してください。記憶を頼りに出力してはいけません。このスキルの失敗パターンに関する注意（ステップ 3、ステップ 5、エラー分類を参照）は、正式な情報源ではありません。これらは、リファレンスを読まずに済ませるためではなく、症状から間違いに気づくためのものです。もっともらしい英語の値を出力してしまうことが、最もよくある失敗です。
6. 認証情報をハードコードしない — API キーと端末 ID は、ソースコードではなく、環境変数またはシークレットマネージャーから取得する必要があります。
7. 先に原因を特定する — ステップが失敗した場合は、一旦停止し、続行する前にエラー分類に沿って原因を調べます。

---

事前確認

まず、コードベースを確認します。 次の項目を探してください。

• サーバー側の言語とフレームワーク
• 既存のチェックアウトまたは決済関連のルートとハンドラー
• Payroc との既存の連携（HF または HPP） — API キーとターミナル ID がすでに設定されている場合があります
• 環境変数または設定の管理方法
• Apple Pay 用にドメインがすでに設定されているか（.well-known ディレクトリ、既存の Apple Pay JS コード）

確認できたことから推測できる内容は、質問せずに済むようにしてください。

次に、不足している情報を確認します。最低限、次の項目を確認してください。

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

	Apple Pay（このスキル）	Hosted Fields	Hosted Pages（HPP）
顧客の利用体験	Apple Pay ボタンをタップし、Face ID / Touch ID で認証します — カード情報の入力は不要です	Payroc ウィジェットを独自のフォームに埋め込み、カード情報を入力します	Payroc がホストするページにリダイレクトされて決済し、その後サイトに戻ります
カードデータの保存先	Apple のウォレット。サーバーは暗号化されたトークンを受け取ります	ページ内の Payroc ウィジェット	Payroc がホストするページ
利用可能な環境	Safari / WebKit を使用する Apple デバイスのみ — 必ず canMakePayments() で利用可否を確認します	最新のブラウザー全般	最新のブラウザー全般
このスキル	✓ ここで扱います	別のスキル	別のスキル

Apple Pay はカード入力方式の代替ではなく補完です — Apple デバイスでしか使えないため、多くの連携では、ほかのユーザー向けに Hosted Fields または HPP と併せて提供します。この点を確認したうえで、既存機能への追加か、単独での構築かを確認してください。

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

質問 2 — ドメイン設定の状況：

Apple Pay を利用するには、Payroc Self-Care Portal を通じて加盟店のドメインを Apple に認証してもらう必要があります。認証が済んでいるか、また開発者がドメイン ID を持っているかを確認してください。

• ドメインの認証済みで、ドメイン ID を利用できる → 加盟店設定の手順を省略します
• まだ認証していない → ステップ 1（加盟店設定）から始めます

続行する前に、開発者からの回答を待ってください。

---

前提条件

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

1. API キー — Payroc の ID サービスから Bearer トークンを取得するために使用します。Hosted Fields で使用するものと同じ認証情報です。Payroc Integrations チームが発行します。
2. 処理端末 ID — Payroc Integrations チームが発行する UAT 端末 ID です。
3. ドメイン ID — Self-Care Portal で販売者のドメインを Apple に認証してもらうと発行されます（ステップ 1 を参照）。すべての Apple Pay セッションリクエストに含めます。コードでは APPLE_PAY_DOMAIN_ID のような変数から読み込めます。
4. 処理端末で Apple Pay が有効になっていること — Self-Care Portal で販売者を設定する前に、Payroc が販売者の処理端末で Apple Pay を有効にする必要があります（ステップ 1）。Payroc Integrations チームに有効化を依頼してください。
5. インターネットからアクセス可能な HTTPS ドメイン — Apple Pay のドメイン認証には、Apple のサーバーがアクセスできる URL が必要です。localhost は認証および実環境テストには不十分で、ステージングまたは本番環境のドメインが必要です。これはインテグレーションの実装を妨げるものではありませんが、認証とテストを妨げます。

不足しているものがあれば、警告してください。作業を止めてはいけません。 コードベースに既存の環境変数の命名規則がないか調べ、あればそれに合わせてください。なければ、PAYROC_API_KEY、PAYROC_TERMINAL_ID、APPLE_PAY_DOMAIN_ID などの名前を提案します。これらの値を環境変数から読み込むコードを実装したうえで、開発者に明確に伝えてください。

⚠️ API キー、端末 ID、Apple Pay ドメイン ID を <VAR names> から読み込むように実装しました。Apple Pay を実際に実行またはテストするには、Payroc UAT 端末と API キー（Payroc Integrations チームにお問い合わせください）、およびインターネットからアクセス可能な HTTPS URL で認証されたドメイン（ステップ 1）が必要です。その間も開発を続けられます。

不足している情報の取得を手伝えることを伝え、希望があれば開発を続けてください。

確認事項

認証情報とドメインが確認されているか、開発者が未対応の項目、その取得方法、コードが読み込む環境変数を把握したうえで、作業を続けることを選択している必要があります。不足項目を伝えないままにしてはいけませんが、それを理由に作業を止めてはいけません。

---

ステップ 1 — 販売者向けに Apple Pay を設定する

参照先：references/set-up-apple-pay-for-a-merchant.md

何か作業する前に、このページを読んでください。参照先に記載された手順を正確に確認してください。ただし、執筆時点では次のとおりです。

0. Payroc が販売者の処理端末で Apple Pay を有効にしていることを確認します。有効になっていない場合、設定を完了できません。
1. UAT 端末用の Self-Care Portal にログインします。
2. Settings → Apple Pay Domains に移動します。
3. Apple Pay ドメイン認証ファイルをダウンロードします。
4. 販売者のドメイン上の /.well-known/apple-developer-merchantid-domain-association にファイルを配置します（HTTPS 経由でインターネットからアクセスできる必要があります）。
5. ポータルでドメインを追加して保存します。
6. 表示されたドメイン IDを控えて安全に保管します。すべての Apple Pay セッションリクエストで必要です。

ポータルでドメインを追加する前に、ドメイン認証ファイルにアクセスできる状態にしてください。 ドメイン登録の手順で Apple がファイルを検証します。

これはポータルおよびホスティングに関する作業であり、開発と並行して進められます。ドメインがまだ認証されていない場合も、作業を止めないでください。APPLE_PAY_DOMAIN_ID 変数を使ってセッションと決済のコードを実装し、Apple Pay の実環境テストを行う前に認証を完了する必要があることを開発者に伝えてください。

確認事項

保存後に Self-Care Portal にドメイン ID が表示され、HTTPS 経由で /.well-known/ パスから認証ファイルを取得できますか？ まだの場合は、テスト時までの未対応項目として記録し、開発を続けてください。

---

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

references/identity-call.md を読みます。正規の Bearer トークン交換リファレンスです。ID エンドポイントの URL、ヘッダー名、レスポンスの形式を推測せず、このファイルに記載されている内容だけを出力してください。 references/add-apple-pay-to-your-integration.md を読みます。Payroc の説明で、Bearer 認証が Apple Pay のフローにどのように組み込まれるかを確認できます。

何かを書く前に、両方を読んでください。リファレンスから次の内容を確認してください。

• ID サービスのエンドポイント
• 必須のヘッダーとその形式
• アクセストークンが含まれるレスポンスフィールド

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

チェックポイント

呼び出しは access_token を含む 200 を返しますか？

---

ステップ 3 — Apple Pay ボタンと支払いシートを実装する

何かを書く前に、2 つのリファレンスを読んでください。

• Payroc の説明（構成）： references/add-apple-pay-to-your-integration.md のクライアント側のセクションです。JavaScript のイベントとサーバーの間で Payroc が何を期待するかをここで確認します。
• Apple の JavaScript API の仕様（形式）： references/third-party/apple-applepaysession.md は、ApplePaySession コンストラクター、すべてのイベント名、すべてのメソッド名、すべてのステータス定数についての派生ノートです。Payroc の説明ではこれらが名前で参照されていますが、正確な綴り、シグネチャ、種類についての正規の情報源ではありません。
• Apple Pay ボタンの描画（形式）： references/third-party/apple-pay-button.md は、ボタンを実際に描画する方法を説明しています。方法は 2 つあり、互換性はありません。CSS の -webkit-appearance: -apple-pay-button を使う方法（スクリプト不要）と、<apple-pay-button> Web コンポーネントを使う方法です（描画には Apple の apple-pay-sdk.js スクリプトの読み込みが必須です）。このノートでは、以下のゲーティングに関する落とし穴も説明しています。apple-applepaysession.md ではボタンの描画について扱っていないため、このファイルを読んでください。

new ApplePaySession(...) または session.* の呼び出しを出力する前に — Apple の派生ノートで確認してください

1. 参照する内容。 Apple の ApplePaySession 派生ノート（references/third-party/apple-applepaysession.md）。また、コンストラクターに必要な paymentRequest の形式も、学習データではなく、このノートで確認してください。
2. 確認する内容。
   • コンストラクターのシグネチャ（new ApplePaySession(version, paymentRequest)）と、現時点で適切な version の値。
   • セッションが実際に発火するイベントハンドラー（onvalidatemerchant、onpaymentauthorized、oncancel など）と、各イベントの正確なペイロード形式。
   • セッションが公開するメソッド（completeMerchantValidation、completePayment、abort など）。
   • ステータス定数（STATUS_SUCCESS、STATUS_FAILURE、および分岐条件に使用するその他の定数）。
3. 確認してから出力してください。 各イベントハンドラーは、Apple の派生ノートに記載された正確な名前で設定してください。各メソッドは、ドキュメントに記載されたインターフェースに対してのみ呼び出してください。存在すると想定したメソッドが派生ノートにない場合、別の名前をでっち上げて再試行しないでください。Apple はその役割を別の場所（たとえば、支払いリクエストのプロパティ）に移している可能性があります。

クライアント側の連携を実装します。

1. 利用可能か確認してボタンを表示する — すべてを ApplePaySession.canMakePayments() で囲みます。これが true を返す場合にのみ Apple Pay ボタンを表示し、それ以外の場合は別の支払い方法を表示してください。ボタンの表示方法については references/third-party/apple-pay-button.md を参照してください — いずれかの方法を選び、完全な形で出力します。CSS の -webkit-appearance: -apple-pay-button ボタン（読み込みは不要）、または必須の apple-pay-sdk.js スクリプトタグを含めた <apple-pay-button> Web コンポーネントのどちらかです（スクリプトがなければ Web コンポーネントは何も表示しません）。非表示が実際に適用されるよう制御してください。 独自の CSS でボタンに display を設定すると、HTML の hidden 属性は暗黙に上書きされます（作成者の CSS はユーザーエージェントの [hidden] ルールより優先されます）。そのため、JS で style.display またはクラスを切り替えるか、ボタンの基本 CSS で display を設定しないようにし、ApplePaySession が存在しない場合にボタンが本当に非表示になることを確認してください。hidden がスタイルシートに必ず優先されると想定しないでください。
2. 必要な paymentRequest オブジェクト（加盟店名、対応ネットワーク、加盟店機能、国コード、通貨コード、合計金額）を指定して ApplePaySession を作成します。対応ネットワークの定数の表記（たとえば "visa" と "Visa" のどちらか）を含め、正確なプロパティ名を Apple の派生ノートで確認してください（このスキルでは派生ノートが正とします）。
3. 加盟店検証イベントを処理する — このイベントは支払いシートが開いたときに発火します。クライアントは、イベントの検証 URL を渡してサーバー（例：POST /checkout/apple-pay/session）を呼び出す必要があります。サーバーは Payroc API を呼び出してセッションを開始し（ステップ 4）、セッションレスポンスを返します。クライアントは Apple のドキュメントに記載された完了メソッド（正確な名前とシグネチャは Apple の派生ノートで確認してください）にレスポンスを渡します。
4. 支払い承認イベントを処理する — 顧客が Face ID／Touch ID で承認すると発火します。イベントには暗号化された支払いデータが含まれます。クライアントはこのデータをサーバーに送信して処理し（ステップ 5）、その後、ドキュメントに記載された成功／失敗のステータス定数を指定して、ドキュメントに記載された支払い完了メソッドを呼び出します。
5. セッションの開始メソッドを呼び出す — 支払いシートを表示します（正確な名前は Apple の派生ノートで確認してください）。

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

症状を認識できるように列挙しています。修正方法は常に、Apple の派生ノート（references/third-party/apple-applepaysession.md）を読み、そこに記載されている内容を出力することです。「以下の値を使う」ことではありません。

• 症状： 想定していたハンドラー名が呼び出されません。支払いシートは開きますが、加盟店の検証手順が何も通知されずにスキップされます。以前の誤り： 実際の API はイベントベース（セッションに設定する on* ハンドラー）なのに、session.validateMerchant() のようなメソッド形式の呼び出しを作り出していました。確認方法： 派生ノートにイベントが列挙されています。記載されたイベント名に従い、セッションのプロパティとしてハンドラーを設定してください。
• 症状： completePayment は呼び出しを受け付けますが、シートが正しく閉じない、またはステータス定数が拒否されます。以前の誤り： STATUS_OK などのステータス定数や、誤った引数の形式を作り出していました。確認方法： 派生ノートに、ApplePaySession クラスでエクスポートされるステータス定数が記載されています。正確な名前を使用してください。
• 症状： セッションコンストラクターやボタンのレンダリングで、ブラウザー側の TypeError が発生します。以前の誤り： コンストラクターに誤った数の引数を渡していたか、クラスに存在しないメソッドを呼び出していました。確認方法： 派生ノートに、コンストラクターのシグネチャーとメソッドの全一覧が記載されています。
• 症状： 利用可能なカードがある Safari でも、Apple Pay ボタンがまったく表示されません（高さが 0、またはグリフが表示されません）。以前の誤り： Apple の apple-pay-sdk.js スクリプトを読み込まずに <apple-pay-button> Web コンポーネントを出力していたため、カスタム要素が登録されていませんでした。確認方法： references/third-party/apple-pay-button.md を確認してください。Web コンポーネントを使う場合は SDK スクリプトを読み込むか、代わりに CSS の -webkit-appearance: -apple-pay-button を使用してください。
• 症状： 非 Apple 製ブラウザーでは非表示にすべき Apple Pay ボタンが、ゲートで hidden 属性を設定しているにもかかわらず表示されます。以前の誤り： 作成者 CSS のルールでボタンに display を設定し、ユーザーエージェントの [hidden] { display: none } ルールを上書きして、ゲートを無効にしていました。確認方法： references/third-party/apple-pay-button.md を確認してください。hidden 属性だけに頼らず、JS で style.display／クラスを切り替えて制御し、ApplePaySession が存在しない場合にボタンが実際に非表示になることを確認してください。

チェックポイント

Apple 製デバイスまたはシミュレーターでボタンをタップすると、Apple Pay の支払いシートが表示されますか？ 加盟店の検証イベントは発火しますか？

---

ステップ 4 — Apple Pay セッションを開始する

参照先：references/api-schema.md（applePaySessions の両方のスキーマセクション — terminal-path バリアントと payments-path バリアント）および references/add-apple-pay-to-your-integration.md（セッション開始の説明）。

トレーニングで得た知識に基づいて、エンドポイント URL、フィールド名、レスポンス形式を使用しないでください。実装するバリアントを選ぶ前に、references/api-schema.md で両方のセッション開始エンドポイントのスキーマを確認してください。

Apple Pay セッションの開始に対応したエンドポイントは 2 つあります。コードを出力する前に、references/api-schema.md を読んで、それぞれの正確なスキーマを確認してください。

バリアント	エンドポイント	processingTerminalId の場所	使用するケース
Payments-path（新規 — 推奨）	POST /v1/payments/apple-pay/sessions	リクエストボディ	新規のインテグレーション
Terminal-path（従来）	POST /v1/processing-terminals/{processingTerminalId}/apple-pay-sessions	URL パス	すでにこのパスを使用している既存のインテグレーション

新規のインテグレーションでは、payments-path バリアントを実装してください。すでに terminal-path バリアントを使用している既存のインテグレーションでは、移行は不要です。どちらもサポートされています。

onvalidatemerchant が発生したら、サーバーから Payroc API を呼び出して、Apple とのセッションを検証する必要があります。参照先を確認してください。

• 使用するエンドポイントのバリアント（テスト環境と本番環境それぞれの正確な URL）
• 選択したバリアントで必須のリクエストボディフィールド（references/api-schema.md の該当するスキーマセクションを確認してください）
• completeMerchantValidation に渡すレスポンスオブジェクト

Payments-path バリアントのボディ（references/api-schema.md の applePaySessions (payments-path variant) を参照）：

• processingTerminalId — 必須（URL パスから移動）
• appleDomainId — ステップ 1 のドメイン ID
• appleValidationUrl — イベントの validationURL をそのまま使用

Terminal-path バリアントのボディ（references/api-schema.md の applePaySessions (start-session request body) を参照）：

• appleDomainId — ステップ 1 のドメイン ID
• appleValidationUrl — イベントの validationURL をそのまま使用
• processingTerminalId — リクエストボディではなく、URL パスに指定

どちらのバリアントも同じ applePayResponseSession 形式を返します：{ startSessionResponse: "..." }。startSessionResponse はラップを解除して completeMerchantValidation に渡してください。

次の処理を行うサーバーサイドのエンドポイントを実装してください。

1. クライアントから validationURL を受け取ります
2. 有効な Bearer トークンを生成（または再利用）します
3. 正しいボディフィールドを指定して、選択した Payroc のセッション開始エンドポイントに POST します
4. レスポンスボディをクライアントに返します

チェックポイント

completeMerchantValidation は成功しますか（エラーがスローされませんか）？決済シートは開いたままで、支払いカードの表示まで進みますか？

---

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

このステップでは2 つの情報源を参照します。イベントから渡される暗号化トークンの形式は Apple が定めており、/v1/payments に POST する際のラップ形式と列挙値は Payroc が定めています。両方の参照先を読んでください。

• Apple Pay 決済トークンの形式（Apple の情報をもとにしたメモ）： references/third-party/apple-payment-token.md — 承認イベントから渡される payment.token.paymentData ペイロードの形式です。ここにはトークンの JSON 構造が記載されており、その JSON を 16 進数にエンコードしてから Payroc に送信します。
• Payroc の説明とスキーマ： 構成については references/add-apple-pay-to-your-integration.md、正確なフィールド名と列挙値については references/api-schema.md（paymentRequest、paymentMethod の digitalWallet バリアント）を参照してください。

トレーニングで得た知識に基づいて、フィールド名、エンドポイント URL、暗号化データ形式を使用しないでください。 2 つの変換には、それぞれ別の情報源があります。Apple のトークン形式は references/third-party/apple-payment-token.md に、Payroc の決済リクエスト形式は references/api-schema.md に記載されています。コードを出力する前に両方を読んでください。 決済承認イベントが発生すると、イベントには Apple からの暗号化された決済データが含まれます。サーバーでは、次の処理が必要です。

1. イベントから暗号化された決済データを抽出します（データの形式は、Apple の決済トークンから導き出されたメモを参照してください。トレーニングデータから推測しないでください）。
2. 16 進数形式に変換します（Payroc API で必要です。Payroc の説明文で正確な要件を確認してください。明記されていない場合は、references/api-schema.md で encryptedData フィールドに記載された制約を確認してください）。
3. Payroc の決済エンドポイントに POST します。送信する構造は（references/api-schema.md を参照）、一般に次のようになります。
   • paymentMethod.type — references/api-schema.md のデジタルウォレットに関する現在の enum 値（paymentMethod.type enum）を確認してください。記憶に頼って "digitalWallet" と決めつけないでください。
   • paymentMethod.serviceProvider — Apple Pay に関する現在の enum 値を references/api-schema.md で確認してください。記憶に頼って "apple" と決めつけないでください。
   • paymentMethod.encryptedData — 手順 2 で 16 進数にエンコードしたトークンです。
   • 標準の channel、processingTerminalId、order フィールドも含めます（すべて確認してから出力してください。下記の enum に関する注意を参照）。
   • order.orderId — 決済ごとに生成する一意の識別子で、1～24 文字に制限されています（references/api-schema.md で制約を確認してください）。下記の orderId に関する注意を参照してください。
4. HTTP 201 の場合は、Apple 由来のメモに記載されたクライアント上の決済完了メソッドを、記載された成功ステータス定数とともに呼び出します。
5. エラーが発生した場合は、同じメソッドを記載された失敗ステータス定数とともに呼び出し、決済シートが適切に閉じるようにします。

Payroc の channel enum は references/api-schema.md で確認してください。 channel は Payroc の決済リクエストに含まれるもので、Apple Pay セッションには含まれません。過去に発生した既知の失敗（関連する別の連携事例より）： ブラウザー内のチェックアウトにふさわしい値に聞こえたため、モデルが channel: "internet" を出力し、Payroc はエラー詳細に enum の一覧を含む HTTP 400 を返しました。ここで正しい値を暗記するのではなく、リクエストボディを組み立てる際にスキーマリファレンスから 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 などは成功ではなく、approved は enum のメンバーではありません。過去に発生した既知の失敗（関連する別の連携事例およびベンチマークより）： モデルが承認時の status のリストを作成した（または "approved" の場合のみ分岐した）結果、実際の承認を誤って失敗として処理しました。ステータスの集合を記憶に頼って列挙しないでください。成功分岐は responseCode === 'A' を基準にし、status はライフサイクルの判定に使ってください。E（後続処理）と P（一部承認）は適切に処理してください。D／R／C は拒否として扱ってください。

order.orderId は 1～24 文字に収めてください。 references/api-schema.md で制約を確認してください（order.orderId の長さは 1～24 文字です）。過去に発生した既知の失敗： モデルが order-${uuidv4()}（42 文字）や crypto.randomUUID() の生の値（36 文字）を生成し、Payroc がすべての決済を HTTP 400 "orderId size must be between 1 and 24" で拒否したため、成功分岐に到達できませんでした。UUID/GUID の生の値は制約に収まりません。必ず収まる方式を使ってください。たとえば、短い 16 進数 ID（crypto.randomBytes(8).toString('hex') → 16 文字）、数文字のランダム文字列を付けた base36 タイムスタンプ、または加盟店独自の短い注文番号を使えます。orderId は完全な連携処理の中の多数のフィールドのうちの 1 つにすぎないため、簡単に間違える可能性があります。必ず制約を満たす方式を意図的に出力してください。

チェックポイント

決済 API は UAT で HTTP 201 を返しますか？ Apple Pay の決済シートに成功確認が表示されますか？

---

ローカルテスト戦略

Apple Pay には、localhost では満たせない到達性の要件が 2 つあります。どちらも上記で説明していますが、 見つけやすいようにここにまとめます。

• ボタンを表示してシートを開くには、Wallet にカードを登録した実際の Apple デバイスまたはシミュレーターで、Safari / WebKit を使用する必要があります（それ以外の場合、canMakePayments() は false を返します。エラー分類を参照してください）。
• ドメインの検証（前提条件とステップ 1）には、パブリックにアクセス可能な HTTPS ドメインが必要です。 Apple のサーバーは /.well-known/apple-developer-merchantid-domain-association ファイルを直接取得するため、 localhost は検証できません。ステージングドメイン、または HTTPS 経由で検証ファイルを配信するトンネル（ngrok、VS Dev Tunnels、Cloudflare Tunnel）を使用し、そのドメインを Self-Care Portal に登録してください。

このフローに受信 Webhook はありません。パブリックな到達性が必要なのは、ドメイン関連付けファイルだけです。

---

エラー分類

症状	考えられる原因	対処方法
Apple Pay ボタンがまったく表示されない	canMakePayments() が false を返している	Wallet にカードを追加した Apple デバイスまたはシミュレーターでテストしてください。ペアリングされた iPhone で Apple Pay が有効になっていれば、macOS の Safari でも動作します
カードを追加した Apple デバイスでも、Apple Pay ボタンが何も表示されない（高さがゼロ／グリフが表示されない）	<apple-pay-button> Web コンポーネントを、Apple の apple-pay-sdk.js スクリプトを読み込まずに使用しているため、カスタム要素が登録されていません	references/third-party/apple-pay-button.md を参照してください。apple-pay-sdk.js のスクリプトタグを追加するか、CSS の -webkit-appearance: -apple-pay-button を使う方法に切り替えてください
Apple 製ではないブラウザーでも Apple Pay ボタンが表示される（非表示になるべき環境）	作成者の CSS ルールでボタンに display が設定されており、ユーザーエージェントの [hidden] { display: none } ルールが上書きされているため、hidden による制御が機能していません	references/third-party/apple-pay-button.md を参照してください。JS で style.display／クラスを切り替えて制御するか、ボタンの基本 CSS で display を設定しないようにしてください。ApplePaySession が存在しない場合に実際に非表示になることを確認してください
Payments API が 400 "orderId size must be between 1 and 24" を返す	order.orderId が 24 文字を超えています。通常は、生の uuidv4()／crypto.randomUUID()（36 文字）か、UUID に接頭辞を付けた値です	references/api-schema.md の order.orderId の 1～24 文字という制約を確認してください。常に制限内に収まる方式（短い 16 進数、短いランダム値を付けた base36 のタイムスタンプ、または短い加盟店注文番号）を使用してください
onvalidatemerchant が発火するが、completeMerchantValidation が例外をスローする	セッション開始 API の呼び出しに失敗したか、レスポンスが生の Apple セッションオブジェクトではありません	Payroc のレスポンス全体をログに記録してください。ラップされたオブジェクトではなく、レスポンス本文が completeMerchantValidation に直接渡されていることを確認してください
セッション開始が 404 を返す	エンドポイント URL が間違っているか、パス内の processingTerminalId が正しくありません（端末パス形式の場合）	references/api-schema.md でエンドポイント URL を再確認してください。端末 ID が UAT 端末のものであることを確認してください
セッション開始が 400 を返し、processingTerminalId を名指しした必須フィールド不足エラーが発生する	Payments パス形式（POST /v1/payments/apple-pay/sessions）を使用しているのに、リクエスト本文に processingTerminalId がありません。このエンドポイントでは、これはパスパラメーターではなくなっています	references/api-schema.md（Payments パス形式のスキーマ）を確認し、リクエスト本文に processingTerminalId を追加してください
セッション開始が 400 を返す	appleDomainId または appleValidationUrl がないか、無効です	Self-Care Portal でドメイン ID を確認してください。validationURL がイベントから変更されず、そのまま渡されていることを確認してください
Self-Care Portal でドメイン検証に失敗する	検証ファイルに HTTPS 経由でアクセスできません	ファイルが拡張子なしで /.well-known/apple-developer-merchantid-domain-association に配置されていることを確認してください。ドメインを追加する前に curl でテストしてください
Payment API が 401 を返す	Bearer トークンの有効期限が切れているか、API キーが間違っています	Bearer トークンを再取得してください。x-api-key の値を確認してください
Payment API が 400 を返す	encryptedData が 16 進数形式ではないか、必須フィールドが不足しています	encryptedData の形式要件を再確認してください。Apple の支払いデータから 16 進数への変換が正しいことを確認してください
STATUS_SUCCESS の後に決済シートで失敗が表示される	Payment API が 201 以外を返したのに、誤って成功として扱われています	成功判定は HTTP 201 のみに厳密に限定してください。それ以外のすべてのステータスは失敗として扱ってください
Payments API が HTTP 400 を返し、エラー詳細で "channel"（または別の列挙型フィールド）を示し、受け付け可能な値の一覧が表示される	列挙型にない値が出力されています（関連する統合での過去の失敗例：channel: "internet"、"online"、"ecommerce"）。文書化された値の代わりに、もっともらしく聞こえる類似の値を使っています	references/api-schema.md で channel（または該当するフィールド）を確認し、記載されている値のいずれかを出力してください。英語としてもっともらしいかどうかから列挙型の値を推測しないでください
paymentMethod.type または paymentMethod.serviceProvider が Payroc API に拒否される	スキルが references/api-schema.md を確認せず、トレーニングデータで記憶した digitalWallet／apple の値を出力しました	references/api-schema.md で現在の paymentMethod.type と paymentMethod.serviceProvider の列挙値を確認し、そこに記載されている値を出力してください。記憶していた値がたまたま正しくても、参照資料を読まなかったという規律違反そのものがバグです
Apple Pay セッションのコンストラクターが TypeError をスローする、または on<event> ハンドラーが呼び出されない	Apple の派生ノートではなくトレーニングデータからコンストラクターのシグネチャやイベント名を使っており、想定した名前が文書化されたインターフェースと一致していません	Apple の ApplePaySession 派生ノート（references/third-party/apple-applepaysession.md）を確認してください。コンストラクターのシグネチャ、接続するすべてのイベント名、呼び出すすべてのメソッドを確認してください。創作したり名前を変更したりしないでください。想定した名前が派生ノートにない場合、その役割は Apple によって別の場所に移されています
アプリは決済失敗を記録したが、実際には銀行が承認していた — Payroc のレスポンスでは responseCode: "A" と approvalCode／OK メッセージが示されている	推測した transactionResult.status の一部だけを成功条件にしていました（過去の失敗例：「approved」のみを受け付けていたが、これは列挙型の値でもありませんでした。または pending などの承認済み状態を除外した承認状態のリストを使用していました）	references/api-schema.md に従い、responseCode === 'A' を成功分岐の判定に使用してください。ready と pending は承認済みとして扱い、status はライフサイクルの状態としてのみ扱ってください。承認状態の集合を記憶から列挙しないでください

---

検証チェックリスト

• API キーとターミナル ID は環境変数から取得し、ソースコードには記載しない
• ベアラートークンはサーバー側で生成し、ブラウザーに公開しない
• Apple Pay ボタンは ApplePaySession.canMakePayments() が true を返す場合にのみレンダリングし、Apple Pay が利用できない場合に実際に非表示になることを確認する（作成者 CSS で hidden 属性を上書きしてゲートを無効化しない）
• Apple Pay ボタンは、文書化された方法で描画する：CSS の -webkit-appearance: -apple-pay-button、または apple-pay-sdk.js のスクリプトタグを読み込んだうえでの <apple-pay-button>
• order.orderId は 1～24 文字で生成し、生の UUID/GUID は使用しない
• ドメイン検証ファイルに HTTPS 経由で /.well-known/apple-developer-merchantid-domain-association からアクセスできる
• ドメイン ID は安全に保存し（環境変数または設定ファイル）、ハードコードしない
• onvalidatemerchant：validationURL はイベントからサーバーへそのまま渡し、サーバーのレスポンスは completeMerchantValidation にそのまま渡す
• onpaymentauthorized：暗号化データを Payroc API に送信する前に 16 進形式に変換する
• テスト用 Apple Pay トランザクションを使用した UAT で、決済 API が HTTP 201 を返す
• 決済 API のレスポンス後、正しいステータスを指定して session.completePayment() を呼び出す

---

アンチパターン

Apple Pay ボタンを無条件にレンダリングする — Apple 製以外のデバイスや Safari 以外のブラウザーでは、何も通知されずに失敗します。必ず canMakePayments() で条件を確認してください。

CSS でボタンの display を強制しながら、hidden 属性で条件を確認する — 作成者 CSS（例：.apple-pay-button { display: block }）は、ユーザーエージェントの [hidden] { display: none } ルールを上書きするため、条件によって hidden が設定されてもボタンが表示されます。代わりに JS で style.display またはクラスを切り替え、ApplePaySession が存在しない場合にボタンが実際に非表示になることを確認してください。references/third-party/apple-pay-button.md を参照してください。

SDK スクリプトを読み込まずに <apple-pay-button> Web コンポーネントを出力する — カスタム要素は https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js が読み込まれた場合にのみ登録されます。読み込まないとボタンは何も描画されません。スクリプトを読み込むか、CSS の -webkit-appearance: -apple-pay-button を使用してください。references/third-party/apple-pay-button.md を参照してください。

order.orderId に生の UUID を使用する — uuidv4()／crypto.randomUUID()（36 文字）や接頭辞付きの形式は 1～24 文字の制限を超えるため、Payroc は決済を HTTP 400 で拒否します。必ず制限内に収まる方式を使用してください。

validationURL を変更する — Apple のイベントからそのまま渡してください。エンコードやトリミングなど、変更を加えると加盟店の検証に失敗します。

セッション開始のレスポンスをラップする — Apple の completeMerchantValidation が要求するのは、Payroc API が返す生のセッションオブジェクトです。別のオブジェクトでラップしたり、再度 JSON エンコードしたりしないでください。

決済 API のレスポンス前に completePayment(STATUS_SUCCESS) を呼び出す — completePayment を呼び出す前に、必ず Payroc API のレスポンスを待ってください。早まって呼び出すと、セッションが未定義の状態になります。

ドメイン ID をハードコードする — ドメイン ID は UAT と本番のポータルで異なるため、環境変数から取得してください。

---

完了

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

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

• ドメインの検証 — ドメインは Self-Care Portal を通じて Apple に登録されています。ドメイン ID によりセッションリクエストが承認されます。
• 加盟店の検証 — Apple Pay シートが開くと、サーバーが Payroc を呼び出して Apple とのセッションを検証します。顧客には信頼できる決済エクスペリエンスが表示されます。
• 決済処理 — 顧客が Face ID / Touch ID で承認すると、サーバーが暗号化された決済データを 16 進数に変換し、Payroc の決済エンドポイントに送信します。
• UAT で検証済み — Apple Pay のエンドツーエンドの取引を確認しました。

本番稼働の前に： セッション開始の呼び出しと決済 API 呼び出しの両方で、UAT エンドポイント URL を本番 URL に置き換えてください（api.uat.payroc.com → api.payroc.com）。決済パスのバリアントを使用する場合は、https://api.uat.payroc.com/v1/payments/apple-pay/sessions → https://api.payroc.com/v1/payments/apple-pay/sessions に変更してください。本番用 Self-Care Portal に本番ドメインを登録し、そのドメイン ID を取得してください。

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

• Google Pay — Google Pay を並行して利用できるデジタルウォレットの選択肢として追加します。フローは似ていますが、Google Pay JS API と異なる serviceProvider 値を使用します。
• Hosted Fields — Apple Pay を利用できないユーザー向けに、開発者がカード入力フォームのフォールバックも必要とする場合は、Hosted Fields スキルを使用します。