integrate-payment-links

Name: integrate-payment-links
Author: payroc

github.com/payroc開発044 回インストール4 週間前に更新

リポジトリ

integrate-payment-links について

Payroc Payment Links の連携を支援する開発者向けスキルです。リンクの作成、共有、ライフサイクル管理を扱い、ローカルの API 資料に基づいて REST/JSON リクエストを案内します。

主な機能

01支払いリンクの作成と共有
02リンクの取得、検索、更新
03リンクの無効化と共有履歴の確認
04取引と金額方式の設定
05API 資料に基づくリクエストと列挙値の確認
06認証、冪等性、エラーへの対応

活用シーン

01メールなどで支払いリンクを送付
02請求書や注文用の支払い窓口を作成
03リンクの状態や有効期限を管理
04UAT で支払いリンクのフローをテスト

MCP 対応

README では MCP 接続確認ツールの任意実行に触れていますが、このスキルが MCP サーバーを提供または管理するとは記載されていません。

インストール

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

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

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

同梱ファイル

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

references/

_sources.md

api-schema.md

create-and-share-a-payment-link.md

error-response-format.md

extend-your-integration.md

idempotency.md

identity-call.md

詳細

Payroc Payment Links の統合

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

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

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

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

Payroc Payment Links の統合 セットアップから動作する統合の構築までご案内します。リンクの作成、必要に応じたメールでの共有、ライフサイクルの管理を行います。

Payment Links の仕組み：

Payroc の API を呼び出して決済リンクを作成します。URL が返されます

あなた（または Payroc のメールサービス）が、その URL を顧客と共有します

顧客がリンクをクリックし、Payroc がホストする決済ページで支払います

リンクは completed に遷移するか（1回限り）、active のままになります（複数回利用可能）

Payment Links、Hosted Pages、Hosted Fields の違い：

Payment Links — URL を生成し、好きな方法（メール、SMS、請求書）で共有します。サイト上にチェックアウトフォームを用意する必要はありません。このスキルで扱います。

Hosted Pages（HPP） — 顧客はサイトでチェックアウトを開始し、フローの途中で Payroc の決済ページにリダイレクトされた後、サイトに戻ります。別のスキルで扱います。

Hosted Fields — Payroc のカード入力ウィジェットを、独自のチェックアウトフォームに直接埋め込みます。リダイレクトはありません。別のスキルで扱います。

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

クイックリファレンス

POST  https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links
Authorization:   Bearer <token>
Idempotency-Key: <uuid-v4>
Content-Type:    application/json

リファレンス

すべての列挙値とスキーマは、以下のローカル references/ ファイルに記載されています。このスキルはライブ参照や記憶からではなく、これらのファイルに基づいて処理します。Payment Links は純粋な REST/JSON API であり、フォーム POST の仕組みはありません。

ソース	ローカルファイル	用途
API スキーマリファレンス	`references/api-schema.md`	すべての列挙値、必須フィールド、リクエスト／レスポンスのスキーマ、チャージの形式、JSON Patch 操作
エラーレスポンス形式	`references/error-response-format.md`	エラーエンベロープ（RFC 7807）＋ Payroc の errors[] ＋標準エラータイプのカタログ
作成と共有のガイド	`references/create-and-share-a-payment-link.md`	作成と共有の手順を説明するガイド
拡張機能ガイド	`references/extend-your-integration.md`	取得、一覧表示、更新、無効化、共有イベント

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

コア原則

質問する前に調査する — 何かを尋ねる前にコードベースを読み、見つけた内容を活用して、明白な質問を省き、的を絞った質問をします。
コーディングする前に質問する — 実装コードを書く前に、インテークを通じて不明点を確認します。誤った前提は開発者の時間を無駄にします。
列挙値を出力する前に、必ずスキーマリファレンスを読む。 固定された文字列の集合を受け付ける各フィールド（type、authType、paymentMethods[] の値、status、sharingMethod、JSON Patch の op 値）は、references/api-schema.md に記載されています。このスキルの正式な参照元は同ファイルです。値を出力する前に必ず読み、学習データに基づいて推測してはいけません。もっともらしく聞こえても、ドキュメントに記載されていない文字列を指定すると、400 エラーまたは通知されない不一致が発生します。同じルールは開発者から提供されたコードをレビューする場合にも適用されます。列挙値やフィールド名が正しいか判断する前に references/api-schema.md を確認し、記憶だけで正しいと判断してはいけません。
/deactivate を除くすべての POST と PATCH に Idempotency-Key を付ける。 ヘッダー値は UUID v4 でなければなりません。これは必須ヘッダーであり、省略可能ではありません。省略すると 400 エラーになります。操作ごとに新しい UUID を生成し、異なるリクエスト間で同じキーを再利用してはいけません。例外は POST /v1/payment-links/{paymentLinkId}/deactivate のみで、このリクエストではヘッダーを受け付けません。ここでヘッダーを送っても問題ありませんが、省略しても 400 エラーにはなりません。
認証情報をハードコードしない。 API キーと端末 ID は、バージョン管理にチェックインされたソースコードや設定ファイルではなく、環境変数またはシークレットマネージャーから取得します。
ベアラートークンの有効期限。 ID サービスから発行されるトークンは 3,600 秒（1 時間）後に期限切れになります。短いスクリプトであれば問題ありませんが、長時間稼働するサービスではトークン更新ロジックを実装してください。
次に進む前に検証する — UAT で現在のステップのチェックポイントに合格するまで、次のステップに進んではいけません。
先に診断してから進む — ステップに失敗した場合は一時停止し、先に進む前にエラー分類に沿って原因を確認します。

インテーク

まずコードベースをスキャンします。 次の項目を確認します。

サーバー側の言語とフレームワーク
既存の請求書、注文、請求関連のコード
既存の HTTP クライアント設定や認証情報の設定
環境変数の管理方法

見つかった情報を使って明白な回答を事前に入力し、的を絞った質問をします。その後、次のチェックリストを提示します。開発者の回答に基づいて、実装するセクションを決定します。

インテグレーションで必要な機能は何ですか？該当するものをすべて選ぶよう開発者に依頼してください。

[常に含める] 決済リンクを作成する（必須のコア機能）
Payroc の API を使ってリンクをメールで共有する
特定のリンクの詳細を取得する
端末のすべてのリンクを一覧表示／検索する
リンクを更新する（有効期限、ラベル、または金額を変更する）
リンクを恒久的に無効化する
共有履歴を表示する（共有イベントを一覧表示する）
今後の請求に備えて決済情報をトークン化／保存する（credentialOnFile）

次の点も確認します。

リンクの種類： 1 回限り（支払いが 1 回正常に完了すると completed になる）、または複数回（支払い回数に制限なし）？
取引の種類： 売上（即時に請求）、または事前承認（資金を確保し、後で売上処理）？
決済方法： カード、銀行振込、または両方？
金額： 固定（設定する金額）、または顧客入力（入力を求める）？

回答に基づいて、該当しないセクションは省略します。開発者のユースケースが曖昧な場合（例：「請求書を送りたい」）は、進む前に要点を絞った確認質問を 1 つします。

前提条件

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

API キー — Payroc の ID サービスから Bearer トークンを生成するために使用します。UAT アクセスとともに、Payroc Integrations チームから提供されます。
処理端末 ID — リンク作成エンドポイントのパスで使用する processingTerminalId です。開発者は UAT のセットアップ時にこの値を把握しているはずです。
UAT 環境 — Payroc のテスト環境です。セルフサービスでのサインアップはできません。UAT 端末は Payroc Integrations チームが手動でプロビジョニングします。

不足しているものがあれば、警告してください。作業を止めてはいけません。 コードベースを調べて、既存の環境変数の命名規則があればそれに合わせてください。なければ、PAYROC_API_KEY や PAYROC_TERMINAL_ID のような名前を提案してください。認証情報をそれらの環境変数から読み取るコードを書いたうえで、開発者に次の内容をはっきり伝えてください。

⚠️ API キーと端末 ID を <VAR names> から読み取るように実装しました。実際に実行またはテストするには、Payroc の UAT 端末と API キーが必要です。入手するには Payroc Integrations チームに連絡し、テスト前に環境変数を設定してください。それまでの間も開発を続けられます。

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

チェックポイント

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

ステップ 1 — 認証

認証コードを出力する前に references/identity-call.md を読んでください。エンドポイント URL、ヘッダー名、レスポンスの形式を推測してはいけません。参照ドキュメントに記載されている内容だけを使用してください。

エンドポイント：

UAT／テスト：POST https://identity.uat.payroc.com/authorize
本番環境：POST https://identity.payroc.com/authorize

ヘッダー：x-api-key: <api-key>

レスポンスには access_token、expires_in（3600）、token_type（"Bearer"）が含まれます。以降のすべての API リクエストでは、Authorization: Bearer <access_token> を使用します。

開発者が使用する言語で、トークン生成ヘルパーを実装してください。本番コードには、有効期限の追跡と更新処理を含めてください。処理中にトークンの有効期限が切れると、リクエスト自体が正しくても 401 エラーが発生します。

API キーは環境変数（例：PAYROC_API_KEY）に保存してください。コードに直接埋め込んではいけません。

チェックポイント

ヘルパーはエラーなく Bearer トークンを生成できますか？できない場合は、x-api-key ヘッダーを確認し、API キーが UAT 環境用として正しいことを確認してください。

ステップ 2 — 決済リンクを作成する

エンドポイント：POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links

必須ヘッダー：

Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <UUID v4>

リクエストボディを書く前に references/api-schema.md を読んでください。 type、authType、paymentMethods 配列の要素、charge オブジェクトの構造はすべて、そこに定義されています。これらを学習データから出力しないでください。契約の正本はリファレンスです。

ヒアリングの回答に基づいて実装する、主な選択事項：

必須フィールドの全項目をリファレンスで確認してください。 必須フィールドのリストを記憶に頼らないでください。references/api-schema.md のリンク作成リクエストスキーマを読み、ルートレベルで必須のフィールド（例：merchantReference）と、リンクタイプに応じて必須となるフィールドを確認してください。開発者のコードをレビューする際、必須フィールドの不足は記憶ではなく、スキーマリファレンスに基づいて指摘してください。「任意に見える」フィールドが必須の場合もあります。

リンクタイプ

singleUse — 決済の成功は1回のみ許可されます。スキーマによると、シングルユースリンクには追加フィールド（order オブジェクト内の orderId や、YYYY-MM-DD 形式の expiresOn など）が必要です。正確な条件付き必須項目を references/api-schema.md で確認してください。決済後、リンクは completed に遷移します。
multiUse — 無制限の決済を受け付けます。シングルユース専用のフィールドは不要です。

取引タイプ（authType）

sale — 資金が即時に引き落とされます
preAuthorization — 資金が保留されます。後で決済の ID を使用してキャプチャエンドポイントを呼び出す必要があります

決済方法

card、bankTransfer、または両方を含む配列です。記述する前に、references/api-schema.md で有効な値を確認してください
銀行振込＋マルチユース＋事前承認は有効な組み合わせですが、実例で見かける頻度は低めです。カードのみのフローのパターンに頼らず、必ずリファレンスを確認してください

課金 — charge は、type フィールドで判別される 単一のフラットなオブジェクトです。preset と prompt は type が取る値であり、その下にネストするキーではありません。金額と通貨のフィールドは、type と 同じ階層に並びます。

// preset — you set the amount
"charge": { "type": "preset", "amount": 10000, "currency": "GBP" }

// prompt — customer enters the amount at payment time (no amount field)
"charge": { "type": "prompt", "currency": "GBP" }

よくある間違い — preset のネストに関する落とし穴。 "charge": { "preset": { "amount": …, "currency": … } }（またはネストした prompt キー）と記述するのは誤りで、API は 400 エラーで拒否します。preset／prompt というキーは存在しません。preset／prompt は type の値であり、amount／currency は type と同じ階層に並びます。開発者のコードをレビューする際は、この点を明確に指摘してください。ネストした preset／prompt のラッパーを削除する必要があり、単に「type フィールドを追加する」だけではありません。このスニペットが示すのは構造のみです。正確な charge スキーマと追加フィールドの有無は、references/api-schema.md を読んで確認してください。

レスポンスから paymentLinkId と assets.paymentUrl を取得してください。これらは以降のすべての操作に必要です。

チェックポイント

API は paymentLinkId と assets.paymentUrl を含む HTTP 201 を返しますか？返さない場合は、エラーの分類を確認してください。

ステップ 3 — メールで共有する

(開発者が「リンクをメールで共有」を選択した場合、このセクションを含めてください)

エンドポイント：POST https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/sharing-events

必須ヘッダー：

Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <UUID v4>      ← generate a new UUID; do not reuse Step 2's key

リクエストボディ：

{
  "sharingMethod": "email",
  "recipients": [
    { "name": "Customer Name", "email": "[email protected]" }
  ],
  "message": "Optional message to include with the payment link",
  "merchantCopy": false
}

sharingMethod の値を書く前に references/api-schema.md を読んでください。 推測ではなく、文書に記載された列挙値を使用してください。

レスポンス（HTTP 201）には、追跡用の sharingEventId が含まれます。アプリケーションで共有履歴が必要な場合は、これを保存してください。

チェックポイント

API は sharingEventId を含む HTTP 201 を返しますか？返さない場合は、paymentLinkId が正しいことと、Idempotency-Key が新しい UUID であることを確認してください。

ステップ 4 — 拡張機能

(開発者がヒアリング時に選択したサブセクションのみを実装してください)

リンクを取得する

GET https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}

ヘッダー：Authorization: Bearer <token>

現在の status を含む、リンクオブジェクト全体を返します。シングルユースリンクが完了しているか確認する際に便利です。

端末のリンク一覧を取得する

GET https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links

ヘッダー：Authorization: Bearer <token>

クエリフィルターに対応しています：merchantReference、linkType（singleUse／multiUse）、chargeType、status（active／completed／deactivated／expired）、recipientName、recipientEmail、createdOn、expiresOn。

ページネーション：limit、after、beforeのクエリパラメーターを使ったカーソルベースです。レスポンスのhasMoreフィールドは、追加のページがあるかどうかを示します。

フィルターロジックを実装する前に、linkTypeとstatusの正確な列挙値をreferences/api-schema.mdで確認してください。

リンクを更新する（一部更新）

PATCH https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}

必須ヘッダー：Authorization: Bearer <token>、Idempotency-Key: <UUID v4>

リクエストボディはRFC 6902 JSON Patch配列です。PUTボディではありません：

[
  { "op": "replace", "path": "/expiresOn", "value": "2026-12-31" }
]

対応するopの値：add、remove、replace、move、copy、test。パッチ操作の種類と各型の制約については、references/api-schema.mdを参照してください。

**重要：**シングルユースリンクを更新すると、paymentUrlとpaymentButtonが再生成されます。古いURLをすでに配布している場合は、新しいURLを再共有する必要があります。

リンクを無効化する

POST https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/deactivate

必須ヘッダー：Authorization: Bearer <token>

無効化コードを書く前に、これが恒久的で取り消せない**操作であることを開発者に確認してください。無効化されたリンクは次のようになります：

再有効化できません
以降のすべての取得リクエストでdeactivatedステータスを返します
URLを使おうとする顧客は支払いできません

支払いを一時停止することが目的の場合は、代わりにexpiresOnを過去の日付に更新する（PATCHを使用する）ことで目的を達成できるか確認してください。その場合、expiresOnを延長すれば、後でリンクを再有効化できます。開発者が恒久的な無効化を明示的に確認した後にのみ、無効化コードに進んでください。

共有イベントの一覧を取得する

GET https://api.uat.payroc.com/v1/payment-links/{paymentLinkId}/sharing-events

ヘッダー：Authorization: Bearer <token>

フィルター：recipientName、recipientEmail。ページネーション：limit、before、after（カーソルベース。どちらか一方のみを使用してください）。

タイムスタンプ、受信者の詳細、任意のメッセージテキストを含む、ページネーションされた共有イベントの一覧を返します。

エラーの分類

症状	考えられる原因	対処方法
すべてのリクエストで401	トークンがない、期限切れ、またはAPIキーが間違っている	トークンを再生成します。`x-api-key` ヘッダーの値が正しいUAT APIキーであることを確認します
400 — `type`、`authType`、または`paymentMethods`に関するバリデーションエラー	参照資料に記載されていない列挙値が使われている	`references/api-schema.md`を読み、ドキュメントに記載された値を使います
400 — `Idempotency-Key`がない、または形式が不正	ヘッダーがない、またはUUID v4ではない	`/deactivate`以外のすべてのPOSTとPATCHに`Idempotency-Key: <UUID v4>`を追加します。操作ごとに新しいUUIDを生成します
400 — 単回使用リンクに必須フィールドがない	スキーマで必須とされているフィールドがない	`references/api-schema.md`のリンク作成スキーマを読みます。すべての必須フィールドを追加します（単回使用リンクでは通常、`order`内の`orderId`と`expiresOn`が必要です）
400 — chargeオブジェクトが拒否された／形式が不正	`charge`がネストされた`preset`／`prompt`キーでラップされている（`charge.preset.amount`）	フラットな形式にします。`charge`は、`type`（`preset`／`prompt`）と、`type`と同じ階層にある`amount`／`currency`で構成される1つのオブジェクトです。ネストされたラッパーは使いません
409 — `Idempotency-Key`が重複している	異なる操作で同じキーが再利用されている	個別の操作ごとに新しいUUIDを生成します
PATCHによって`paymentUrl`が予期せず再生成される	単回使用リンクは仕様上、更新時に再生成される	更新後のレスポンスに含まれる新しいURLを再共有します
リンクの`status: expired`により、顧客が支払いできない	`expiresOn`を過ぎている	リンクを引き続き有効にする場合は、PATCHで`expiresOn`を延長します
リンクの`status: deactivated`により、顧客が支払いできない	リンクが完全に無効化された	新しいリンクを作成します。無効化されたリンクは再有効化できません
支払いリンクのエンドポイントで404	`paymentLinkId`が間違っているか、リンクが存在しない	作成時のレスポンスに含まれるIDを確認します。一覧エンドポイントでリンクの存在を確認します
事前承認：資金が保留されているが、キャプチャされない	キャプチャの手順が実装されていない、または呼び出されていない	Payments APIの支払いIDを使ったキャプチャ処理を実装します。事前承認は発行会社の保留期間が過ぎると期限切れになります

バリデーションチェックリスト

完了

すべてのチェックリスト項目に合格したら：

統合が完了しました。 構築した内容は次のとおりです。

認証 — Payroc の ID サービスからの Bearer トークン生成。認証情報は環境変数に保存します。

支払いリンクの作成 — [要約：type、authType、paymentMethods、charge type]

メールで共有（実装した場合）— Payroc の API を介して受信者に支払い URL を送信し、sharingEventId を保存します。

拡張機能（実装した機能を列挙）— 取得、一覧表示、更新、無効化、共有イベント。

UAT で検証済み — エンドツーエンドのフローを確認しました。

本番稼働前に： api.uat.payroc.com を api.payroc.com に、identity.uat.payroc.com を identity.payroc.com に置き換えてください。認証情報を本番環境のターミナルと API キーに設定してください。

次のステップを提案してください：

トークン化／継続課金 — credentialOnFile を使用して支払い情報を保存し、今後の加盟店起点の請求に利用します
Webhook 通知 — Payments API をポーリングする代わりに、サーバー側で支払いイベントを受信します
Hosted Fields — Payroc のカード入力ウィジェットを独自のチェックアウトフォームに直接埋め込みます（リダイレクトなし）

Markdown 対応

ログインしてコメント

基本情報

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

問題を報告