integrate-hosted-payment-pages

Name: integrate-hosted-payment-pages
Author: payroc

github.com/payroc開発046 回インストール今日更新

integrate-hosted-payment-pages について

Payroc Hosted Payment Page の導入を開発者向けに案内するスキルです。一回払い、事前承認、継続課金を扱い、項目や API 仕様の根拠となるローカル資料と、任意のバックグラウンド検証 Webhook の手順を示します。

主な機能

01Hosted Payment Page フローの導入
02売上と事前承認への対応
03カード保存と継続課金の設定
04ローカルの API スキーマと項目資料
05任意のバックグラウンド検証 Webhook

活用シーン

01Web サイトへの Payroc 決済ページ導入
02事前承認後のキャプチャ API 呼び出し
03カード保存による定期支払い
04サーバー間通知の検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/payroc/skills --skill integrate-hosted-payment-pages

インストール後、Claude Code で/integrate-hosted-payment-pagesを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

_sources.md

api-schema.md

authenticate-your-requests.md

build-receipt-page.md

error-response-format.md

identity-call.md

implement-background-validation.md

load-hosted-payment-page.md

pre-auth.md

recurring.md

repeat-payments-api-schema.md

sale.md

references/save-payment-details/

authenticate-your-requests.md

build-receipt-page.md

load-hosted-payment-page.md

詳細

Payroc Hosted Pages 統合

対象範囲：CNP（カード非対面）Hosted Pages — 1 回限りの売上取引、事前承認、および継続課金（Hosted Page で顧客のカードを保存し、その後、Payroc のゲートウェイサブスクリプションまたは加盟店起点の独自の課金を通じて繰り返し支払いを受け付けます）。

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

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

上記のフロントマターにある metadata.version フィールドから、このスキルのバージョンを読み取ります。
公開版を取得し、その metadata.version を読み取ります。 https://raw.githubusercontent.com/payroc/skills/main/plugins/payroc/transaction/skills/integrate-hosted-payment-pages/SKILL.md
2 つのバージョンをセマンティックバージョンとして比較します。
- このバージョン >= 公開版 → 何も伝えず、そのまま続行します。（未公開の新しいバージョンを開発者が実行している場合も、想定内で問題ありません。）
- このバージョン < 公開版 → 開発者に次のように伝えます。
  
  ⚠️ このスキルの新しいバージョン（v<published>）が公開されています — 現在実行中のバージョンは v<current> です。最良の結果を得るため、アップグレードをおすすめします。
  
  現在のバージョンで続行するか、いったん停止して先にアップグレードするかを尋ね、回答に従います。
- 取得できなかった場合（オフライン、ネットワークエラー、404）→ バージョンを確認できなかったことを簡潔に伝え、続行します。

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

Payroc Hosted Pages 統合 認証情報の設定から UAT でのテスト取引の成功まで案内します。 Payroc の Hosted Payment Page を介したカード非対面決済を対象としています。売上取引、事前承認（今すぐ与信枠を確保し、後で売上を確定）、継続課金（後で使うカードを保存し、スケジュールに従って、またはオンデマンドで課金）について説明します。

HPP の仕組み（3 つのステップ）：

チェックアウトから Payroc の HPP エンドポイントに POST を送信します。これにより決済ページが読み込まれます

顧客は Payroc のホスト型ページで決済を完了するか、カードを保存します

Payroc は顧客のブラウザーを領収書 URL にリダイレクトし、クエリパラメーターとして取引の詳細を付加します

注：オプションの Background Validation webhook もあります。これは、設定した別の URL に Payroc のサーバーから送信されるサーバーサイド POST です。これは拡張手順であり、上記のメインフローには含まれません。

HPP と Hosted Fields の違い： ページ遷移なしで独自フォーム内に埋め込めるカード入力ウィジェットが必要な場合は、Hosted Fields を使用します。これは別の製品であり、このスキルの対象外です。開発者が埋め込み型カードフォームについて尋ねているようであれば、その旨を伝えてください。

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

クイックリファレンス

REST API 呼び出し（売上確定、サブスクリプション、MIT 決済）を実装するときは、Bearer トークンの交換方法について references/identity-call.md を読んでください。Identity エンドポイント URL、ヘッダー名、レスポンスの形式を推測してはいけません。参照ドキュメントに記載された内容のみを使用してください。

# Identity service (Bearer token — used for REST APIs: capture, repeat payments)
# UAT/test: identity.uat.payroc.com · Production: identity.payroc.com (note: UAT has the .uat segment, prod does not)
POST https://identity.uat.payroc.com/authorize
x-api-key: <api-key>

# Hosted Payment Page — sale (form POST, loads the payment page)
POST https://payments.uat.payroc.com/merchant/paymentpage
Content-Type: application/x-www-form-urlencoded

# Hosted Payment Page — pre-auth (form POST)
POST https://payments.uat.payroc.com/merchant/preauthpage

# Hosted Payment Page — save a card / tokenize (form POST; ACTION=register|update)
POST https://payments.uat.payroc.com/merchant/securecardpage

# Capture API (pre-auth only)
POST https://api.uat.payroc.com/v1/payments/{uniqueRef}/capture
Authorization:  Bearer <token>
Content-Type:   application/json

# Repeat payments — gateway path (Bearer token)
POST https://api.uat.payroc.com/v1/processing-terminals/{terminalId}/payment-plans
POST https://api.uat.payroc.com/v1/processing-terminals/{terminalId}/subscriptions

# Repeat payments — your-own-software / MIT path (Bearer token; paymentMethod.type=secureToken)
POST https://api.uat.payroc.com/v1/payments

参照資料

すべての値と形式は、以下のローカル references/ ファイルに記載されています。このスキルはライブの参照情報や記憶からではなく、それらのファイルを参照して出力します。相互に補完する 3 つの情報源があり、それぞれ異なる種類の疑問を扱います。質問に不適切な情報源を使うことは、既知の失敗要因です。

API スキーマのリファレンス（references/api-schema.md、references/repeat-payments-api-schema.md）— Payroc の JSON API における値と構造の信頼できる情報源：api-schema.md では、事前承認のキャプチャ API と transactionResult スキーマ（responseCode と status の列挙値を含む）を扱います。repeat-payments-api-schema.md では、Secure Tokens、Payment Plans、Subscriptions の各リソースに加え、加盟店起点の課金に使用する Payments の secureToken／standingInstructions の構造を扱います。REST API 側の列挙値やスキーマに関する質問は、これらを参照してください。
HPP の解説ガイド（references/authenticate-your-requests.md、references/load-hosted-payment-page.md、references/build-receipt-page.md、および references/save-payment-details/ 配下のカード保存版）— HPP フォーム POST の信頼できる情報源：HMAC のフィールド順とアルゴリズム、AMOUNT と DATETIME の形式、POST フィールド名と使用可能な列挙値（PAYMENTMETHOD、ACTION、STOREDCREDENTIALUSE、country、language など）、RESPONSECODE や CARDREFERENCE を含むレシートコールバックのクエリパラメーター構造を扱います。HPP フォーム POST は OpenAPI 仕様には含まれていません。これらの解説資料がその正式な情報源です。カード保存フローには独自の資料があります。エンドポイント、ハッシュの生成方法、フォームフィールド、レシートの RESPONSECODE の列挙値が売上フローとはすべて異なるためです。
バックグラウンド検証ガイド（references/implement-background-validation.md）— サーバー間 Webhook の信頼できる情報源：POST されるフィールド名と署名検証を扱います。

「キャプチャ API のリクエストボディの構造と、返される transactionResult の値は？」という質問なら、references/api-schema.md を参照してください。「サブスクリプションの設定や、保存済みトークンを使った加盟店起点の課金に必要なエンドポイント／フィールド／列挙値は？」という質問なら、references/repeat-payments-api-schema.md を参照してください。「HPP フォーム POST に必要なフィールドとハッシュの生成方法は？」という質問なら、HPP の解説資料（カード保存フローの場合は save-payment-details/ 配下の資料）を参照してください。「レシートコールバックで使用できる RESPONSECODE の値は？」という質問なら、売上／事前承認の場合は references/build-receipt-page.md、カード保存の場合は references/save-payment-details/build-receipt-page.md を参照してください（このスキルに例が記載されていても、値の一覧を記憶して答えないでください）。

ソース	ローカルファイル	用途
API スキーマリファレンス	`references/api-schema.md`	Capture API、`transactionResult` スキーマ、Payroc REST API のフィールド／列挙値全般
エラーレスポンス形式	`references/error-response-format.md`	エンベロープ形式のエラー（RFC 7807）＋ Payroc の errors[] ＋標準エラータイプカタログ
リピート決済 API スキーマ	`references/repeat-payments-api-schema.md`	Secure Tokens、Payment Plans、Subscriptions のエンドポイント／列挙値、Payments の `secureToken` ＋ `standingInstructions`（MIT）
認証（HMAC のフィールド順、AMOUNT／DATETIME の形式）	`references/authenticate-your-requests.md`	売上／事前承認のハッシュ生成方法 — 信頼できる情報源
Hosted Payment Page の読み込み（POST フィールド＋列挙値）	`references/load-hosted-payment-page.md`	売上／事前承認の HPP フォーム POST のフィールド名と有効な列挙値 — 信頼できる情報源
レシートページの構築（RESPONSECODE の列挙値＋レシートコールバックフィールド）	`references/build-receipt-page.md`	売上／事前承認のレシートコールバックのクエリパラメーター — RESPONSECODE の値やその他のレシートフィールドについての信頼できる情報源
カードの保存 — 認証	`references/save-payment-details/authenticate-your-requests.md`	カード保存（登録／更新）のハッシュ生成方法 — 信頼できる情報源（AMOUNT なし、MERCHANTREF ＋ ACTION）
カードの保存 — ページの読み込み	`references/save-payment-details/load-hosted-payment-page.md`	カード保存のフォーム POST — `securecardpage` エンドポイント、`ACTION`、`STOREDCREDENTIALUSE`（大文字）— 信頼できる情報源
カードの保存 — レシート	`references/save-payment-details/build-receipt-page.md`	カード保存のレシートコールバック — `CARDREFERENCE`、`STOREDCREDENTIALTXTYPE`、`A`／`E14`／`E43`／`E44` の RESPONSECODE 列挙値 — 信頼できる情報源
売上フロー（ステップ 2～4）	`references/sale.md`	売上フロー（フィールド／列挙値の確認には上記の説明資料を参照）
事前承認フロー（ステップ 2～4）	`references/pre-auth.md`	事前承認フロー（説明資料と、キャプチャについては `api-schema.md` を参照）
定期決済フロー（カード保存＋リピート決済）	`references/recurring.md`	定期決済フロー（`save-payment-details/` の資料と `repeat-payments-api-schema.md` を参照）
バックグラウンド検証	`references/implement-background-validation.md`	Webhook の検証フロー
Bearer トークンの交換（REST API 呼び出し）	`references/identity-call.md`	Identity サービスのエンドポイント URL、`x-api-key` ヘッダー、レスポンス形式 — キャプチャ＋サブスクリプションの認証に関する信頼できる情報源

これらは、このスキルにおける信頼できるローカルスナップショットです。ソース URL と最終同期日は references/_sources.md に記録されています。古くなっているようであれば、そこから再生成してください。

基本原則

質問する前に調査する — 質問する前にコードベースを読み、見つけた情報を使って、明らかな質問を省き、的を絞った質問をしてください。
コーディングする前に質問する — 実装コードを書く前に質問で不明点を解消してください。誤った思い込みは開発者の時間を無駄にします。
次に進む前に検証する — 開発者が現在のステップのチェックポイントが UAT で合格したと確認するまで、次のステップに進まないでください。
推測せず、リファレンスを読み、質問に合ったリファレンスを選ぶ。 HPP には 2 つではなく、3 つのソース領域があります。質問に対して誤った領域を使うと、記憶しているものの誤った値が混入します。ステップ 1 のハッシュレシピでは、すでにこの原則を厳密に適用しています。これを他のすべてのステップにも適用してください。
- HPP フォーム POST とレシートコールバック（PAYMENTMETHOD、RESPONSECODE、AMOUNT/DATETIME の形式、ハッシュフィールドの順序）→ HPP の説明文書。 これらはフォーム POST 領域にあり、references/api-schema.md にはありません。説明文書である references/authenticate-your-requests.md、references/load-hosted-payment-page.md、references/build-receipt-page.md がこれらの正本です。フォーム POST フィールドを出力したり、レシートコールバック値に基づいて分岐したりする前に、該当する説明文書を読んでください。
- キャプチャ API およびその他の Payroc REST API 領域 → references/api-schema.md、定期支払い REST 領域 → references/repeat-payments-api-schema.md。 事前承認向けのキャプチャエンドポイント、transactionResult スキーマ（responseCode と status の全 enum を含む）は api-schema.md にあります。Secure Tokens／Payment Plans／Subscriptions エンドポイントと、Payments の secureToken および standingInstructions の形式は repeat-payments-api-schema.md にあります。フィールド名、enum 値、必須フィールド、リクエスト／レスポンス形式を確認してください。
- カード保存フローは売上フローの派生であり、売上フローにフィールドを追加したものではありません。 エンドポイント（/merchant/securecardpage）、ハッシュレシピ（TERMINALID:MERCHANTREF:DATETIME:ACTION:SECRET — AMOUNT は含まず、MERCHANTREF と ACTION を使用）、フォームフィールド（ACTION、STOREDCREDENTIALUSE）、レシートフィールド（CARDREFERENCE、STOREDCREDENTIALTXTYPE）、レシートの RESPONSECODE enum（A／E14／E43／E44）はすべて異なります。references/save-payment-details/ から確認してください。売上用のレシピをそのまま流用しないでください。
- 保存済みクレデンシャルの用途を示す表記は、領域によって大文字・小文字が異なります。 HPP フォーム POST では 大文字の STOREDCREDENTIALUSE（RECURRING）を使用します。REST API では小文字の mitAgreement／processingModel（recurring）を使用します。対象の領域に合った大文字・小文字で出力してください。
- サブスクリプションを作成する前に、Payment Plan と Secure Token が必要です。 ゲートウェイのフローでは、まず Payment Plan を作成し、次にプランとトークン（トークンは HPP の CARDREFERENCE）を関連付ける Subscription を作成します。プランが存在する前にサブスクリプションを POST しないでください。
- 処理順序と検証パターン → フローファイル。 検証エンドポイントを呼び出すタイミング、Webhook 署名を検証する順序、レシートへのリダイレクトとバックグラウンド検証の組み合わせ方、カード保存から定期支払いへの順序を確認してください。フローファイル（sale.md、pre-auth.md、recurring.md）はフローを説明し、api-schema.md／repeat-payments-api-schema.md は JSON API 側の値を、HPP の説明文書はフォーム POST 側の値を説明します。
- リクエストとレスポンスのスキーマは異なります — レスポンスの形式（例：キャプチャのレスポンス、サブスクリプションのレスポンス）が必要な場合は、リクエストのスキーマとは別に確認してください。リクエストボディからレスポンスの形式を推測しないでください。
- 類推して enum 値を推測しないでください。 もっともらしく聞こえても、ドキュメントに記載のない文字列を使うと API エラーになります。ステップ 1 の「トレーニングデータに含まれるアルゴリズム名は使わない」という原則は、ハッシュレシピだけでなく、PAYMENTMETHOD、RESPONSECODE の分岐、transactionResult.status、キャプチャレスポンスコードなど、すべての値に適用されます。
値ごとに、読んでから出力する。 POST フィールドの enum 値（PAYMENTMETHOD、国、言語）、RESPONSECODE の分岐、キャプチャ API の enum（transactionResult.status、transactionResult.responseCode）、ハッシュ入力のフィールド名を出力する前に、該当するローカルリファレンスを読んでください（フォーム POST 値については HPP の説明文書、キャプチャと transactionResult については references/api-schema.md）。このスキルの例（承認を示す RESPONSECODE=A、拒否を示す RESPONSECODE=D など）を網羅的なものとして扱わないでください。これらは例示であり、正本ではありません。リファレンスに全種類が記載されています。読まなければ、全種類は把握できません。
クレデンシャルをハードコードしない — ターミナル ID、シークレット、API キーは、ソースコードではなく環境変数またはシークレットマネージャーから取得してください。
先に原因を特定してから進む — ステップが失敗した場合は、一時停止し、エラー分類に沿って原因を調べてから続行してください。

インテーク

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

サーバー側の言語とフレームワーク
既存のチェックアウト、注文、決済に関連するルートとハンドラー
HPP の部分的な実装（ハッシュ関数、決済 URL へのフォーム送信、レシートエンドポイント）
環境変数や設定の管理方法
注文や取引の識別方法（ORDERID の方針を理解するため）

推測できる内容を質問せずに済むよう、見つけた情報を活用し、開発者自身が使っている用語に合わせて追加の質問を組み立ててください。そのうえで、まだ必要な情報を尋ねます。決めつけてはいけません。

少なくとも、先に進む前に次の3つのルーティングに関する質問への回答が必要です。

質問 1 — 統合タイプ：

	Hosted Pages（HPP）	Hosted Fields
顧客体験	一時的にサイトを離れ、Payroc のホストページで決済した後に戻ります	サイトを離れることなく、Payroc のカード入力ウィジェットが独自フォームに埋め込まれます
レシートページ	ブラウザーからクエリパラメーター付きの GET リダイレクトを受け取ります	まったく異なるフローです
このスキル	✓ ここで対応しています	フェーズ 2 — まだ対応していません

Hosted Pages → このスキルで続行します
Hosted Fields → まだ対応していません。違いを説明し、代わりに Hosted Pages で続けるか、ここで終了するかを確認します

質問 2 — 継続課金／保存済みカード： この統合では、後で使うために顧客のカードを保存したり、継続課金／サブスクリプション／分割払いを行ったりする必要がありますか？

いいえ → 以下の1回限りの CNP フロー（売上および／または事前承認）に進みます。
はい → 継続課金フローです。2つの段階があります。Hosted Page でカードを保存する（トークン化 → CARDREFERENCE を取得）、その後、繰り返し決済を行うことです。繰り返し決済の方法として、どちらを希望するか尋ねてください。
- Payroc のゲートウェイを使う — Payroc がスケジュールを保存し、決済を回収します（Payment Plans + Subscriptions）。Payroc に課金サイクルを管理してもらいたい場合に最適です。
- 独自のソフトウェアを使う — 独自のシステムで、保存済みトークンを使って加盟店主導の課金をスケジュールし、実行します（POST /payments と paymentMethod.type: secureToken）。すでに課金ロジックがある場合に最適です。
継続課金が対象となる場合、以下のステップ 1～3 はカード保存用の手順に置き換え、ステップ 5 — 繰り返し決済を設定するを追加します。ステップ 1 に進んだら、references/recurring.md を読んでください。

質問 3 — 取引タイプ： この統合では、事前承認（今すぐ資金を確保し、後でキャプチャする）、通常の売上（即時に承認してキャプチャする）、または両方が必要ですか？

売上のみ → 以下の標準フローに進みます
事前承認または両方 → レシートハンドラーの後に追加のキャプチャステップが必要であることを伝え、加盟店アカウントで事前承認を利用できることを確認します（二重価格設定、サーチャージプログラム、コンビニエンスフィーでは利用できません）。ステップ 2 に進んだら、標準手順に加えて references/pre-auth.md を読んでください。

3つすべてが対象として確認できたら、前提条件に進みます。

前提条件

これらは、UAT で統合を実行してテストするために必要なものであり、コードを書くためのものではありません。開発者がすでに用意しているなら問題ありません。まだ用意できていなくても、作業を止める必要はありません。各値を環境変数（レシート URL は設定）から読み取るようにコードを組み込み、開発を続けてください。テストの前に、開発者がすべての値を設定できます。

Terminal ID — Payroc Integrations チームから割り当てられる UAT の端末 ID です。UAT は Payroc のテスト環境です。認証情報はチームによって手動でプロビジョニングされます（セルフサービスでのサインアップはありません）。
Terminal secret — 対象の UAT 端末用にSelf-Care Portalで作成します。
Receipt URL — Payroc の HPP が決済後、取引の詳細をクエリパラメーターとして付加して顧客のブラウザーをリダイレクトする、アプリケーション上の URL です。Payroc のサーバーからの呼び出しではなく、ブラウザーのリダイレクトであるため、この手順のテストにはlocalhost で問題ありません。ライブテストで正常にリダイレクトされるには、UAT 端末の Self-Care Portal に URL を登録しておく必要があります。ただし、今のうちにレシート処理ルートを作成し、URL を設定から読み取るようにできます。

不足しているものがあれば、警告はしても作業は止めないでください。 コードベースで既存の環境変数の命名規則を確認し、それに合わせてください。規則がない場合は、PAYROC_TERMINAL_ID、PAYROC_TERMINAL_SECRET、PAYROC_RECEIPT_URL などの設定名を提案してください。これらの値を環境変数／設定から読み取るコードを作成し、未対応の項目と入手方法を開発者に伝えてください。

Terminal ID／UAT アクセス → Payroc Integrations チームに連絡します。
Terminal secret → UAT アクセスを取得した後、Self-Care Portal で作成します。
Receipt URL → 今すぐルートを決めてハンドラーを作成します。ライブリダイレクトをテストする前に、Self-Care Portal に URL を登録し（ローカルテストのセクションに記載されたトンネリングの選択肢も確認します）、登録を済ませます。

この時点で必要な情報がほかにもあれば確認してください。たとえば、UAT 認証情報がすでにどこかに保存されているか、ゼロから作成するのではなく既存のチェックアウトハンドラーを変更するのか、といった点です。

開発者が端末の認証情報をすでに確認している場合（例：端末 ID とシークレットが環境変数または設定にあることを確認済みの場合）は、ライブテスト前に登録する必要がある主な未対応項目として Receipt URL を伝えてください。ただし、それを待つのではなく、設定済みの URL を使うレシートハンドラーを作成してください。

チェックポイント

Terminal ID、Terminal secret、Receipt URL の確認が済んでいるか、開発者が未対応の項目、その入手／登録方法、およびコードが値を読み取る環境変数と設定を把握したうえで、作業を進めることを選択しています。不足項目を説明せずに残してはいけませんが、それを理由に作業を止めてもいけません。

Step 1 — リクエストを認証する

ご利用のフローのリファレンスをお読みください。

売上／事前承認： references/authenticate-your-requests.md
カードを保存（継続課金）： references/save-payment-details/authenticate-your-requests.md — まず references/recurring.md をお読みください。カード保存から継続決済までの全体の流れが順を追って記載されています。

このステップでは、学習時に得た知識からアルゴリズム名、書式文字列、フィールド名を使わないでください。ハッシュアルゴリズム、AMOUNT の書式、DATETIME の書式、フィールド順序など、すべての値を、ご利用のフローに対応するローカルのリファレンスから確認してください。

継続課金：カード保存用のハッシュのレシピは異なります。 TERMINALID:MERCHANTREF:DATETIME:ACTION:SECRET です。AMOUNT は含まれず、ORDERID の代わりに MERCHANTREF を使用し、さらに ACTION が加わります。売上用のものではなく、そのリファレンスに記載されたハッシュの例を再現してください。売上用のハッシュ関数を変更せずに流用すると、カード保存のリクエストはすべて失敗します。

何かを書く前に、リファレンスを最後までお読みください。そこから以下を確認し、使用してください。

ハッシュアルゴリズム
ハッシュ入力文字列に含める正確なフィールドとその順序
AMOUNT の書式 — よく確認してください。自明ではなく、間違えるとすべてのリクエストが原因の分かりにくいエラーで失敗します
DATETIME の書式とタイムゾーンの要件
検証用のハッシュの例 — 次に進む前に、これを正確に再現してください

開発者が使用している言語とフレームワークで、ハッシュ関数を実装してください。リファレンスの例に記載された入力値を使って、すぐにテストしてください。ハッシュの例は厳密な仕様です。関数が一致しない場合は、バグがあります。

チェックポイント

ハッシュ関数は、リファレンスのハッシュの例を正確に再現できていますか？できていない場合は、先に進む前にエラー分類に従って原因を特定してください。

Step 2 — ホステッド決済ページを読み込む

ご利用の取引タイプに対応するリファレンスをお読みください。

売上： references/sale.md — Step 2
事前承認： references/pre-auth.md — Step 2
カードを保存（継続課金）： references/recurring.md — Stage A、Step 2（ACTION と STOREDCREDENTIALUSE を含む /merchant/securecardpage へのフォーム POST）

すべての POST フィールドの列挙値に、Step 1 と同じ手順を適用してください。 ハッシュ関数を書く前に認証リファレンスを読むのと同様に、列挙型の値（PAYMENTMETHOD、ACTION、STOREDCREDENTIALUSE、国、言語など、特定の文字列の集合を受け付けるすべてのフィールド）を出力する前に、HPP フォームの POST フィールドを説明する記述を読んでください（売上／事前承認：references/load-hosted-payment-page.md、カード保存：references/save-payment-details/load-hosted-payment-page.md）。学習時に得た知識から列挙値を使わないでください。過去に発生した既知の問題（関連する統合事例から）： あるモデルがブラウザー内決済に妥当そうだという理由で channel: "internet" を出力し、ゲートウェイに拒否され、エラーの詳細に列挙値の一覧が返されました。もっともらしい類似値（internet、online、ecommerce、card-not-present）は、この種の失敗で特によく見られます。出力する前に、受け付けられる値の一覧を記載したリファレンスをお読みください。カード保存に関する注意： STOREDCREDENTIALUSE はここでは大文字です。エンドポイントは paymentpage ではなく securecardpage です。

注： HPP のレスポンスには取引タイプが含まれません。売上、事前承認、カード保存のいずれかを処理する統合の場合は、HPP フォームを送信する前に、それがどのタイプかを独自の注文モデルに記録してください。

チェックポイント

フォームを送信すると、エラーなくブラウザーが Payroc の UAT ページ（売上／事前承認では決済ページ、カード保存ではセキュアカードページ）にリダイレクトされますか？されない場合は、先に進む前に原因を特定してください。

ステップ 3 — レシートページを構築する

取引タイプに応じたリファレンスを確認してください。

売上: references/sale.md — ステップ 3
事前承認: references/pre-auth.md — ステップ 3（レシートのレスポンスは売上と同じです。UNIQUEREF の永続ストレージ要件が適用されます）
カードを保存（継続課金）: references/recurring.md — ステージ A、ステップ 3（レシートが異なります。保存する CARDREFERENCE、A/E14/E43/E44 の RESPONSECODE 列挙型、個別の Secure Token URL、異なるレスポンスハッシュの順序）

RESPONSECODE の分岐や、その他のレシートコールバック列挙型にも、ステップ 1 の手順を適用してください。 ハンドラーを作成する前に、レシートの説明文を確認してください。売上／事前承認では references/build-receipt-page.md、カード保存では references/save-payment-details/build-receipt-page.md を参照してください。記憶している一部の RESPONSECODE 値だけで分岐しないでください。このスキルのエラー分類にある A / D / R / C は売上の例であり、正式な値の一覧ではありません。また、カード保存の列挙型はまったく異なり（A/E14/E43/E44、A は「保存済み」を意味します）、売上のリファレンスには A 以外の承認コード（例：E）も記載されています。リファレンスを正としてください。過去に見られた既知の失敗パターン： RESPONSECODE == 'A' だけを成功とみなし、正式な値の一覧が記憶していたものより多かったために、実際の承認を誤って分類してしまうことです。リファレンスを読み、そこに記載された値の一覧に基づいて分岐してください。

継続課金：CARDREFERENCE を永続的に保存してください。 これは顧客への請求に再利用するセキュアトークンです。データベースに（MERCHANTREF とともに）保存し、セッション／TempData には保存しないでください。信頼する前に、レスポンスハッシュ（カード保存の順序：TERMINALID:RESPONSECODE:RESPONSETEXT:MERCHANTREF:CARDREFERENCE:DATETIME:SECRET）を検証してください。

チェックポイント

レシートハンドラーは Payroc のリダイレクトを受け取り、エラーなくレスポンスハッシュを検証し、レシートのフィールド（売上／事前承認では RESPONSECODE + UNIQUEREF、カード保存では RESPONSECODE + CARDREFERENCE。後者は永続的に保存）を正しく解析していますか？そうでない場合は、続行する前に原因を調査してください。

ステップ 4 — 取引をテストする

売上: references/sale.md — ステップ 4
事前承認: 売上と同じテスト手順（references/sale.md のステップ 1～5）に加えて、次を実行します。 6. 保存済みの UNIQUEREF を使ってキャプチャ呼び出しを実行します 7. レスポンス本文に transactionResult が含まれる状態で HTTP 200 が返ることを確認します

事前承認のキャプチャについては、成功分岐を作成する前に references/api-schema.md で transactionResult のスキーマを確認してください。 transactionResult.status と transactionResult.responseCode はどちらも列挙型です。過去に兄弟連携で見られた既知の失敗： モデルが status == "approved" の場合だけ分岐し、実際の値は responseCode: "A" / responseMessage: "APPROVAL" を伴う "ready"（承認済み＋キャプチャ待ち）だったため、実際の承認を失敗として誤って扱ってしまいました。transactionResult.status の列挙型全体を確認し、銀行の承認と組み合わさる値をすべて特定して、その全体に基づいて分岐してください。記憶している一部の値だけを使って成功判定を作らないでください。

**カード保存（継続課金）**の場合、ステップ 4 の達成条件は「カードの保存に成功したこと」です。カード保存のレシートで RESPONSECODE=A となり、CARDREFERENCE を取得して保存できている必要があります。その後、ステップ 5 に進み、実際の継続課金を設定してください。

チェックポイント

テストカードで RESPONSECODE=A が確認でき、レスポンスハッシュの検証にも成功していますか？（事前承認：キャプチャでも HTTP 200 が返り、transactionResult の成功分岐を列挙型全体に照らして検証しましたか？カード保存：CARDREFERENCE を取得し、永続的に保存しましたか？）そうでない場合は、エラー分類を使ってください。すべての条件を満たすまで、完了として扱わないでください。

ステップ 5 — 継続課金を設定する（継続課金のみ）

連携で継続課金が必要でない場合は、このステップをスキップしてください。references/recurring.md のステージ B と、すべてのエンドポイント、フィールド、列挙値について references/repeat-payments-api-schema.md をお読みください。

このステージでは、Bearer トークン認証による REST API を使用します（事前承認のキャプチャーと同様に、ID サービスからトークンを取得します）。HPP の HMAC ハッシュではありません。インテークで開発者が選択した方法を使用してください。

Payroc のゲートウェイを使用する — Payment Plan（POST .../payment-plans）を作成し、次に paymentMethod が { "type": "secureToken", "token": "<CARDREFERENCE>" } の Subscription（POST .../subscriptions）を作成します。ゲートウェイがスケジュールに従って課金する（automatic）か、.../pay を使って課金します（manual）。
独自のソフトウェアを使用する（MIT） — POST /payments で各課金を実行します。paymentMethod.type: secureToken とトークンに加えて、order.standingInstructions ブロック（sequence は first の後に subsequent、processingModel は unscheduled／recurring／installment）を指定します。

値に応じた正しいリファレンスをお読みください。 プラン／サブスクリプションの列挙値（type、frequency — fortnightly／yearly に注意、onUpdate、onDelete）と MIT の standingInstructions／channel の列挙値は、references/repeat-payments-api-schema.md に記載されています。類推で推測しないでください。また、大文字と小文字が切り替わる点にもご注意ください。フォームでは契約内容を大文字の STOREDCREDENTIALUSE としましたが、ここでは小文字の mitAgreement／processingModel です。

サブスクリプションを作成する前に、支払いプランとトークンが必要です。 サブスクリプションより先にプランを作成してください。トークンはすでに存在します。HPP の CARDREFERENCE です。

チェックポイント

ゲートウェイの方法：サブスクリプションを作成し、UAT で currentState.status が active になっていますか（該当する場合、manual の /pay が成功していますか）？ MIT の方法：最初の課金で HTTP 200 が返り、transactionResult の成功分岐を references/api-schema.md の完全な列挙値と照合して確認しましたか（実際の承認結果が status: "ready" で responseCode: "A" になる場合があります）？エンドポイント／列挙値を出力する前に、継続課金のスキーマを読みましたか？まだの場合は、エラー分類を確認してください。

ローカルテスト戦略

ステップ 1～3（ハッシュ生成、HPP リダイレクト、レシートページ。販売、事前承認、カード保存が対象）は、すべて localhost でテストできます。レシートへのリダイレクトは顧客のブラウザーによって実行されます。Payroc のサーバーがレシート URL を直接呼び出すことはないため、外部から到達できる必要はありません。（カード保存では、リダイレクトに Self-Care の別フィールドであるSecure Token URLを使用します。こちらも localhost で問題ありません。）

ステップ 4 のキャプチャー（事前承認）とステップ 5 の継続課金（継続課金）は、アプリから Payroc に送信するサーバー間 REST 呼び出しなので、こちらも localhost から実行できます。ただし、必要なのは HMAC ハッシュではなく、ID サービスから取得したBearer トークン（x-api-key → access_token）です。公開 URL やトンネルは不要です。

Background Validation 以降では、公開 URL が必要です。Payroc のサーバーが検証 Webhook エンドポイントに POST するため、localhost は使用できません。選択肢は、簡単なものから順に次のとおりです。

webhook.site — Self-Care Portal で webhook.site の URL を一時的な検証 URL として登録します。POST の生データを取得できるため、ハンドラーを作成する前に正確なレスポンスフィールドを確認できます。後でトンネルを使う予定がある場合でも、最初に試す方法として適しています。
VS Dev Tunnels（Visual Studio および VS Code に組み込み）— .NET アプリに自然な選択肢です。設定をほとんど行わずに、ローカルポートへトンネル接続する永続的な公開 HTTPS URL を作成できます。
ngrok — 言語を問わず、すばやく設定できます。無料プランは開発に使用できます。
Cloudflare Tunnel — 長期間利用する環境に、より適しています。
ステージングホストにデプロイする — トンネルを利用できない場合は、UAT からアクセス可能な任意のホストにデプロイしてテストします。

使用する公開 URL を、UAT ターミナルの Background Validation URL として Self-Care Portal に登録してください（レシート URL とは別のフィールドです）。

エラー分類

症状	考えられる原因	対処方法
リダイレクト直後に HPP からエラーが返る	ハッシュが無効です	`references/authenticate-your-requests.md` を再確認してください。AMOUNT の形式、DATETIME の形式とタイムゾーン、フィールドの順序を確認し、リファレンス内のハッシュ例を使って再実行してください
`RESPONSECODE=D`	取引が拒否されました	UAT では想定される結果です — Payroc のテストカードを使用してください
`RESPONSECODE=R`	照会 — お客様が銀行に問い合わせる必要があります	Phase 1 のテストでは拒否として扱ってください
`RESPONSECODE=C`	カードの紛失・盗難が報告されています	別のテストカードを使用してください
アプリには失敗が記録されたものの、実際には承認されていた — `RESPONSECODE` に `A` 以外の値が含まれていた（過去に確認された値：`E`）	レシートページの分岐処理が `RESPONSECODE == 'A'` のみを成功とみなし、それ以外の承認を誤って失敗として分類していました	`references/build-receipt-page.md` で `RESPONSECODE` の全列挙値を確認してください。銀行承認と対になる値をすべて特定し、それらすべてを分岐処理の対象にしてください — `A` は一例であり、正式な値の一覧ではありません。
事前承認：キャプチャ API は HTTP 200 を返すが、アプリには失敗が記録される — レスポンスには `responseCode: "A"` / `responseMessage: "APPROVAL"` と表示される	サーバー側の成功判定が、記憶に頼った `transactionResult.status` の一部の値だけで分岐していました（過去の失敗例：`"approved"` のみを許可し、承認済みでキャプチャ待ちの `"ready"` を誤って失敗として扱っていました）	`references/api-schema.md` で `transactionResult.status` の列挙値を確認し、銀行承認と対になる値をすべて対象にして分岐してください。
支払い後、レシートページにリダイレクトされない	レシート URL が Self-Care Portal に登録されていないか、登録時に誤字があります	レシート結果はブラウザーの GET リダイレクト（クエリパラメーター）で送信されます — サーバー側の POST ではありません。localhost も使用できます。最も可能性が高い原因は、URL が登録されていないか、Self-Care Portal での誤字です。UAT 端末に登録されている URL と完全に一致することを確認してください。
レスポンスハッシュの検証に失敗する	検証用ハッシュのフィールドまたは順序が間違っています	`references/build-receipt-page.md` を再確認し、ハッシュ化するレスポンスフィールドとその順序を正確に確認してください
フィールドは正しいのにハッシュが一致しない	文字エンコーディングまたは空白文字に問題があります	すべてのハッシュ入力はプレーンな ASCII 文字列である必要があります。いずれかのフィールド値に Unicode 文字、末尾の空白、または改行コードが含まれていないか確認してください
キャプチャ API の呼び出しで 404 が返る	UNIQUEREF が無効か、事前承認の期限が切れています	UNIQUEREF がレシートレスポンスの値と一致することを確認してください。事前承認にはカード発行会社が定める保留期間があり、その期間を過ぎると期限切れになります
キャプチャ API の呼び出しで 409 が返る	事前承認はすでにキャプチャされています	キャプチャを試みる前に注文の状態を確認してください。完了したキャプチャを再試行しないでください
キャプチャ／定期支払い API の呼び出しで 401 が返る	Bearer トークンの期限切れ、または API キーが間違っています	Bearer トークンを再生成し、identity サービスで使用した `x-api-key` の値を確認してください
カード保存：リダイレクト直後に HPP からエラーが返る、またはハッシュが一致しない	売上用のハッシュ生成手順をカード保存にも流用している（AMOUNT を含めている、ORDERID を使用している、または ACTION を省略している）、あるいは `securecardpage` ではなく `paymentpage` に POST している	`references/save-payment-details/authenticate-your-requests.md` を再確認してください。生成手順は `TERMINALID:MERCHANTREF:DATETIME:ACTION:SECRET` です（AMOUNT は含めません）。エンドポイントが `/merchant/securecardpage` であることを確認してください。
カード保存：ゲートウェイが `STOREDCREDENTIALUSE` を拒否する（または REST が `mitAgreement`／`processingModel` を拒否する）	対象のインターフェイスで大文字・小文字の使い方が間違っています	HPP フォームの POST では大文字（`RECURRING`）、REST API では小文字（`recurring`）を使用します。出力するインターフェイスに対応するリファレンスを確認してください。
カード保存：レシートハンドラーが呼び出されない	カード保存のリダイレクト先が Self-Care の間違ったフィールドに登録されています	カード保存のレシート URL には、売上／事前承認用のレシート URL とは別の Secure Token URL フィールドを使用します。そこに登録されていることを確認してください。
カード保存：アプリには失敗が記録されたものの、カードは保存されていた	売上用の `RESPONSECODE` 値を使って分岐しています	`references/save-payment-details/build-receipt-page.md` を確認してください。カード保存の列挙値は `A`／`E14`／`E43`／`E44` で、`A` は保存済みを示します。
サブスクリプション作成時に 4xx が返る	Payment Plan またはセキュアトークンがまだ存在しないか、`paymentPlanId`／`token` が間違っています	先に Payment Plan を作成し、`paymentMethod` を `{ "type": "secureToken", "token": "<CARDREFERENCE>" }` に設定してください。`references/repeat-payments-api-schema.md` を確認してください。
トークンを使った MIT 課金が拒否される／順序が正しく処理されない	`standingInstructions` がないか、`sequence`／`processingModel` が間違っています	初回の課金では `sequence: first`、2 回目以降では `referenceDataOfFirstTxn` を指定した `sequence: subsequent` を使用します。`credentialOnFile.mitAgreement` を送信する場合は、`order` に `standingInstructions` も指定する必要があります。
定期支払いの REST 呼び出しで `channel` が拒否される	`channel` の値が無効です（例：`internet`／`online`／`ecommerce`）	`PaymentRequestChannel` の値は `pos`／`web`／`moto` です — `references/repeat-payments-api-schema.md` を確認し、類推で値を推測しないでください。

検証チェックリスト

アンチパターン

端末 ID またはシークレットのハードコード — ソースコード内の認証情報はバージョン履歴に残り、漏えいする可能性があります。

サンプルハッシュの検証を省略する — ハッシュ関数に少しでも誤り（フィールドの順序違い、誤った AMOUNT 形式、タイムゾーンの誤りなど）があれば、すべてのトランザクションが失敗します。references/authenticate-your-requests.md のサンプルハッシュは契約です。他の作業に取りかかる前に、これを基準に検証してください。

レスポンスハッシュを検証せずに RESPONSECODE を信頼する — 先にハッシュを検証しないと、RESPONSECODE=A を含む偽造 POST によって、レシートページが偽装される可能性があります。

UNIQUEREF を保存しない — これがないと、返金や後続のトランザクションを実行できません。

AMOUNT の形式を推測する — 正しい形式は文書に記載されていますが、直感的には分かりません。必ず確認してください。これを誤ると、すべてのリクエストで無効なハッシュが生成されます。

UNIQUEREF をセッションまたは TempData に保存する — 事前オーソリの統合では、UNIQUEREF を現在のリクエストより後まで保持する必要があります。一時的なストレージを使うと、ユーザーがページを離れたりセッションが期限切れになったりした場合に、売上確定できなくなります。

ステップ 1 の「トレーニング知識から値を一切使わない」という指針を、ステップ 1 に固有のものとして扱う。 このガードレールはハッシュの算出方法だけを対象としていたのではありません。統合で出力したり、条件分岐に使ったりする、文書化されたすべての値に適用される基準です。POST フィールドの列挙値（PAYMENTMETHOD）、RESPONSECODE の分岐、capture API の transactionResult.status の値は、いずれも特定のローカルリファレンス（フォームとレシートについては HPP の説明資料、capture については references/api-schema.md）に記載されています。値を出力したり、それに基づいて分岐したりする前に、該当するリファレンスを確認してください。初期の反復で最も目立つ失敗要因だったのが、たまたまハッシュの算出方法だったにすぎません。

列挙値についての不完全な理解から、成功判定を組み立てる。 これが RESPONSECODE と transactionResult.status の両方の失敗に共通する根本的な誤りです。ローカルリファレンスを読むのではなく、記憶やこのスキルの例から列挙値について推論しています。すべての承認判定では、A や単一のステータスだけでなく、銀行による承認と組み合わされる値をすべて列挙する必要があります。

save-card に売上用のハッシュ関数を使い回す。 save-card の算出方法は TERMINALID:MERCHANTREF:DATETIME:ACTION:SECRET です。AMOUNT は不要で、ORDERID ではなく MERCHANTREF を使い、さらに ACTION を加えます。変更せずにコピーした売上用ハッシュでは、分かりにくいハッシュエラーが発生し、すべての save-card リクエストが失敗します。（AMOUNT の形式を推測するのと同じ種類の誤りです。）

カードの保存／トークン化時に AMOUNT を請求する。 カードの保存は売上ではなく、0 ドルのトークン化です。securecardpage フォームには AMOUNT フィールドがありません。save-card リクエストに金額を含めている場合は、売上のフローと混同しています。

CARDREFERENCE をセッションまたは TempData に保存する。 セキュアトークンは現在のリクエストよりはるかに長く保持する必要があります。翌月に顧客へ請求するために使うものです。事前オーソリの UNIQUEREF と同様に、永続ストレージに保存してください。

支払いプランとトークンが作成される前に Subscriptions を呼び出す。 サブスクリプションはプランとトークンを関連付けるため、両方が先に存在している必要があります。HPP の save-card ではトークン（CARDREFERENCE）はすでに存在するため、先にプランを作成し、その後サブスクリプションを作成してください。

サーフェスごとの保存済み認証情報の大文字・小文字を混同する。 HPP フォームでは大文字の STOREDCREDENTIALUSE、REST API では小文字の mitAgreement／processingModel を使います。これらは同じ契約を表しますが、サーフェスに合わない大文字・小文字を使うとゲートウェイに拒否されます。

完了

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

統合が完了しました。 以下を構築しました。

認証ハッシュ — 端末のシークレットで各決済リクエストに署名し、改ざんを防止します。

チェックアウトハンドラー — 決済フォームを組み立て、Payroc の Hosted Payment Page に POST します。

レシートハンドラー — Payroc からのブラウザーリダイレクト（クエリパラメーター付きの GET）を受信し、レスポンスハッシュを検証し、RESPONSECODE の承認値一式に応じて分岐して、UNIQUEREF を取得します。

UAT で検証済み — テストカードでエンドツーエンドの取引を確認しました。

事前承認＋売上確定（該当する場合） — チェックアウト時に資金を保留し、決済準備が整ったら REST API 経由で売上を確定します。UNIQUEREF がこの 2 つの呼び出しを関連付け、売上確定レスポンスの分岐で transactionResult.status の承認値一式を処理します。

継続課金（該当する場合） — securecardpage を使用して Hosted Page でカードを保存します（独自のハッシュ計算方法とレシートを使用）。CARDREFERENCE を永続的に保存し、Payroc のゲートウェイ（Payment Plan＋Subscription）または独自の加盟店起点の課金（secureToken＋standingInstructions）のいずれかで継続課金を設定し、UAT で検証します。

本番稼働の前に： UAT エンドポイント URL を本番 URL に置き換えてください。これには HPP エンドポイント（paymentpage／preauthpage／securecardpage）とすべての REST エンドポイント（売上確定、payment-plans、subscriptions、payments）が含まれます。リファレンスで確認してください。認証情報を本番端末に設定し、レシート URL（カードを保存する場合は Secure Token URL も含む）が本番の Self-Care Portal に登録されていることを確認し、テストカード番号をすべて削除してください。

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

バックグラウンド検証 Webhook — レシートへのリダイレクトとは独立して、すべての取引でサーバー間 POST を実行します。照合や、リダイレクトに失敗した場合のフォールバックとして便利です。
継続課金のライフサイクル管理（継続課金の場合） — サブスクリプションの更新／無効化／再有効化、保存済みカードの更新（ACTION=update またはセキュアトークン更新エンドポイント）、未払いへの督促に対応します。
Hosted Fields（フェーズ 2） — Payroc がホストするカード入力ウィジェットを独自のフォームに埋め込みます。ページのリダイレクトはありません。

Markdown 対応

ログインしてコメント

基本情報

作者: payroc
リポジトリ: payroc/skills
カテゴリ: 開発
インストール数: 46
GitHub スター: 0

問題を報告