payware

payware MCP Server

payware の決済 API 統合向け公式 MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI アシスタントが payware API と連携し、あらゆるパートナー種別の統合ワークフローを自動化できます。

リリースは npm の @payware/mcp-server と、公式の MCP Registry の io.github.payware/mcp-server として公開されています。MIT ライセンスです。詳しくは LICENSE をご覧ください。

対象ユーザー

• 加盟店 - 決済の受付、商品の管理、取引レポートの生成
• ISV（独立系ソフトウェアベンダー） - OAuth2 トークン管理を備えたマルチ加盟店プラットフォームの構築
• 決済機関 - A2A 送金の処理、複数の決済方法に対応した Payment Choice Architecture の処理

v1.2.0 の新機能

• SHA-256 認証 - JWT コンテンツハッシュ（contentSha256 ヘッダー）を MD5 から SHA-256 にアップグレードしました
• エラーコードの更新 - 新しいエラーコード：ERR_INVALID_CONTENT_HASH、ERR_MISSING_CONTENT_HASH
• 後方互換性 - レガシー環境をサポートするため、非推奨の MD5 関数を引き続き保持しています

機能

🔐 認証ツール

• RSA 鍵の生成：安全な 2048 ビット RSA 鍵ペアを生成します
• JWT トークンの作成：適切な形式の JWT トークンを作成します
• サンドボックスのセットアップ：サンドボックス認証を設定します

💳 取引ツール

• 取引の作成：PLAIN、QR、BARCODE 取引に対応します
• 取引の処理：Payment Choice Architecture に対応した取引を処理します
• 取引ステータス：ID で取引ステータスを確認します
• 取引履歴：確定済みの取引詳細を取得します
• コールバックのシミュレーション：加盟店および決済機関向けのコールバックシナリオをテストします

📍 インタラクションポイント（POI）ツール

• 価格の設定：金額、通貨、決済詳細を指定して POI を設定します
• 価格のキャンセル：POI から有効な価格を消去します
• POI の取得：POI の詳細と現在の状態を取得します
• ステータスの取得：POI の取引ステータスを確認します
• QR コードの取得：POI 決済用の QR コードを生成します
• POI の一覧表示：加盟店のすべての POI を一覧表示します

📣 キャンペーン、プレースメント、放映ツール

加盟店向け、および加盟店に代わって操作する ISV 向けです。変更には加盟店の PRM プランが必要ですが、読み取りはすべてのプランで利用できます。

• プレースメント：ポスター、テレビ広告、パッケージ、リンク、タグを通じて商品を配布します。それぞれに独自の pl ID が割り当てられ、そこから開始されたすべての決済が各プレースメントに関連付けられます。各プレースメントの QR コード、バーコード、短縮リンクも含まれます
• キャンペーン：複数の商品にまたがるプレースメントをまとめ、その合算結果を読み取ります
• 放映ルール：繰り返し、時間帯、タイムゾーンを指定してプレースメントの放映時間をスケジュールし、1 回の呼び出しでスケジュール全体を置き換えます
• 放映カレンダー：指定期間内のすべての商品におけるすべての放映を表示します
• 結果：プレースメントまたはキャンペーンごとに、表示されたオファー、開始および確定した決済、確定金額を表示します

📋 ログツール（プレミアム）

• ログの検索：レベル、ロガー、メッセージ内容、日付範囲でアプリケーションログを検索、絞り込みます
• ログステータス：ログの利用可否とストレージ情報を確認します
• ログのダウンロード：オフライン分析用の圧縮ログアーカイブを取得します

🛠️ ユーティリティツール

• 高度なコード生成：8 言語（Python、Node.js、PHP、Java、C#、Go、Ruby、cURL）に対応し、16 種類以上のフレームワーク向け統合コード一式を生成します
• フレームワーク統合：Django、FastAPI、Express、NestJS、Laravel、Spring Boot、ASP.NET など、フレームワーク固有のサンプルを提供します
• 実環境のシナリオ：統合シナリオ一式（E コマース、ISV マルチ加盟店、P2P 決済）を生成します
• 包括的なドキュメント：コード例を含む API ドキュメント一式を自動生成します
• リクエストの整形：API リクエストを整形し、検証します

クイックスタート

1. インストール

npm から（推奨）：

npm install -g @payware/mcp-server

ソースから：

git clone https://github.com/payware/mcp-server.git
cd mcp-server
npm install

2. 環境設定

環境ファイルのサンプルをコピーし、認証情報を設定します。

cp .env.example .env

.env ファイルを編集します。

# Partner ID from payware dashboard
PAYWARE_PARTNER_ID=your_partner_id_here

# Path to private key file (relative to project root)
PAYWARE_SANDBOX_PRIVATE_KEY_PATH=keys/sandbox-your-private-key.pem
PAYWARE_PRODUCTION_PRIVATE_KEY_PATH=keys/production-your-private-key.pem

# Optional: Sandbox base URL (defaults to https://sandbox.payware.eu/api)
PAYWARE_SANDBOX_URL=https://sandbox.payware.eu/api

⚠️ セキュリティに関する注意：.env ファイルをバージョン管理にコミットしないでください。機密性の高い認証情報が含まれています。

ツールセットの選択

すべてのツール定義は毎ターン、アシスタントのコンテキストに追加されます。加盟店には70を超えるツールがあります。使用するグループだけを提供するには、PAYWARE_MCP_TOOLSETS にカンマ区切りのリストを設定します。

PAYWARE_MCP_TOOLSETS=products,placements

ツールセット：auth、transactions、products、placements、data、logs、poi、shops、onboarding、utils。設定しない場合、または all を指定した場合は、すべてのツールが読み込まれます。不明な名前は無視され、サーバーログに警告が記録されます。選択したツールセットに含まれないツールは、一覧表示も呼び出しもできません。これによりアシスタントに提供されるツールの範囲が絞られますが、パートナーアカウントで実行できる操作は変わりません。このサーバーを通じて OAuth2 トークンを取得する ISV は、auth を含めます。

3. MCP サーバーの起動

npm start

4. 基本的な統合の流れ

1. RSA キーを生成する

   Tool: payware_authentication_generate_rsa_keys
   

2. JWT トークンを作成する

   Tool: payware_authentication_create_jwt_token
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   

3. サンドボックスを設定する

   Tool: payware_authentication_setup_sandbox_auth
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   

4. トランザクションを作成する

   Tool: payware_operations_create_transaction
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   - amount: 10.00
   - currency: EUR
   - reasonL1: "Payment description"
   - type: PLAIN
   

5. ステータスを確認する

   Tool: payware_operations_get_transaction_status
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   - transactionId: TRANSACTION_ID
   

API リクエストの構造

payware MCP サーバーは、フラットなパラメーター入力を payware API が必要とする適切なネストされた JSON 構造に変換します。

トランザクション作成リクエストの構造

{
  // ROOT LEVEL - Transaction metadata
  "shop": "SHOP001",                    // Optional: Shop code
  "account": "GB29NWBK60161331926810",  // Optional: Account identifier
  "friendlyName": "Your Shop Name",     // Optional: Account holder name
  "callbackUrl": "https://callback.url", // Optional: HTTPS callback URL
  "passbackParams": "{\"orderId\":\"12345\"}", // Optional: Callback parameters
  
  // TRANSACTION DATA - Required transaction information
  "trData": {
    "amount": "25.50",              // String/Number: Amount (can be "0.00" for flexible amounts)
    "currency": "EUR",              // REQUIRED: ISO 3-character currency code
    "reasonL1": "Payment for services", // REQUIRED: Transaction description (max 100 chars)
    "reasonL2": "Order #12345"      // Optional: Additional description (max 100 chars)
  },
  
  // TRANSACTION OPTIONS - Transaction behavior settings
  "trOptions": {
    "type": "QR",                   // PLAIN, QR, or BARCODE (default: PLAIN)
    "timeToLive": 300               // Seconds: 60-600 (default: 120)
  },
  
  // QR OPTIONS - Only included when type=QR
  "qrOptions": {
    "qrFormat": "PNG",              // PNG, SVG, JPG, GIF, BMP (default: SVG)
    "qrBorder": 4,                  // Border modules: 1-10 (default: 4)
    "qrErrorCorrection": "QUARTILE", // LOW, MEDIUM, QUARTILE, HIGH (default: QUARTILE)
    "qrScale": 16,                  // Pixel size: 1-100 (default: 16, irrelevant for SVG)
    "qrVersion": 10                 // QR version: 1-40 (default: 10, auto if not specified)
  },
  
  // BARCODE OPTIONS - Only included when type=BARCODE
  "barOptions": {
    "barFormat": "SVG",             // PNG, SVG, JPG (default: SVG)
    "barModuleWidth": 2,            // Module width: 1-10 (default: 2)
    "barBarHeight": 100,            // Height: 15-1000 (default: 100)
    "barFontSize": 12,              // Font size: 0-24 (default: 12)
    "barHumanReadableLocation": "NONE" // NONE, BOTTOM, TOP (default: NONE)
  }
}

パラメーターのマッピング

MCP ツールを使用すると、パラメーターは適切な API 構造に自動的にマッピングされます。

MCP ツールのパラメーター	API の場所	説明
partnerId, privateKey	認証	JWT の署名に使用され、リクエストでは送信されません
account, friendlyName, shop, callbackUrl, passbackParams	ルートレベル	トランザクションのメタデータ
amount, currency, reasonL1, reasonL2	trData オブジェクト	トランザクションの主要データ
type, timeToLive	trOptions オブジェクト	トランザクションの動作
qrFormat, qrBorder など	qrOptions オブジェクト	QR コードの設定（type=QR の場合）
barFormat, barModuleWidth など	barOptions オブジェクト	バーコードの設定（type=BARCODE の場合）

利用可能なツール

コード生成とドキュメント

payware_generate_code_example

フレームワークに対応した高度な多言語コード生成

すべてのパートナータイプにわたる60以上の操作に対応しています。

• トランザクション：create_transaction、get_transaction_status、cancel_transaction、process_transaction、get_transaction_history、simulate_callback
• 製品：create_product、get_product、update_product、delete_product、list_products、get_product_image、create_schedule、update_schedule、delete_schedule、list_schedules
• OAuth2（ISV のみ）：obtain_token、get_token_info、create_token_simple、refresh_token、revoke_token、list_active_tokens
• データ：generate_report、get_report_status、export_report、download_export、cancel_report、list_reports、get_analytics_summary、create_custom_report
• P2P（決済機関）：initiate_p2p_transfer、accept_p2p_transfer、reject_p2p_transfer、get_p2p_transfer_status、list_p2p_transfers、cancel_p2p_transfer、create_p2p_link、get_p2p_analytics
• Soundbites（決済機関）：register_audio、get_audio、update_audio、delete_audio、list_audios、create_soundbite_transaction、stream_audio、download_audio、get_soundbite_analytics、create_audio_playlist、get_audio_preview

payware_generate_documentation

包括的なドキュメント生成ツール

あらゆるパートナータイプと言語の組み合わせに対応した、動作するコード例付きの完全な API ドキュメントを生成します。

認証

payware_authentication_generate_rsa_keys

API 認証用の RSA キーペアを生成します。

パラメーター：

• keySize（任意）：RSA キーのビット数（デフォルト：2048）

payware_authentication_create_jwt_token

API 認証用の JWT トークンを作成します。

パラメーター：

• partnerId（必須）：payware のパートナー ID
• privateKey（必須）：PEM 形式の RSA 秘密鍵

payware_authentication_validate_jwt

JWT トークンの形式と署名を検証します。

パラメーター：

• token（必須）：検証する JWT トークン
• partnerId（必須）：検証に使用するパートナー ID

payware_authentication_test_jwt

payware API で JWT トークンをテストします。

パラメーター：

• token（必須）：テストする JWT トークン
• partnerId（必須）：パートナー ID

payware_authentication_setup_sandbox_auth

サンドボックス認証の設定をセットアップします。

パラメーター：

• partnerId（必須）：payware のパートナー ID
• privateKey（任意）：検証用の秘密鍵

取引

取引ステータスの概要

payware の取引には、以下のステータスがあります。

ACTIVE ステータス：

• ⏳ ACTIVE：処理中または完了待ちのアクティブな取引
• payware_transactions_get_transaction_status が返すステータスはこれのみです
• GET /transactions/{id} エンドポイントを使用します

最終ステータス：

• ✅ CONFIRMED：正常に完了しました
• ❌ DECLINED：ユーザー、処理機関、または決済機関によって拒否されました
• 💥 FAILED：技術的な理由などにより失敗しました
• ⏰ EXPIRED：取引の有効期間が終了しました
• 🚫 CANCELLED：取引の開始者によってキャンセルされました

これらの最終ステータスは、GET /transactions-history/{id} エンドポイントを使用する payware_operations_get_transaction_history でのみ取得できます。

payware_operations_create_transaction

API の全構造に対応した新しい取引を作成します。

主なパラメーター：

• currency（必須）：ISO 3 文字の通貨コード（EUR、USD、GBP など）
• reasonL1（必須）：取引の説明（最大 100 文字）
• partnerId（必須）：payware ダッシュボードのパートナー ID
• privateKey（必須）：JWT 署名用の RSA 秘密鍵
• amount（任意）：通貨単位の金額（柔軟な金額を指定する場合のデフォルトは "0.00"）
• type（任意）：PLAIN、QR、または BARCODE（デフォルト：PLAIN）
• timeToLive（任意）：支払いのタイムアウト時間（秒）、60～600（デフォルト：120）

QR オプション（type=QR の場合）：

• qrFormat：PNG、SVG、JPG、GIF、BMP（デフォルト：SVG）
• qrErrorCorrection：LOW、MEDIUM、QUARTILE、HIGH（デフォルト：QUARTILE）
• qrScale、qrBorder、qrVersion：サイズと外観の設定

バーコードオプション（type=BARCODE の場合）：

• barFormat：PNG、SVG、JPG（デフォルト：SVG）
• barModuleWidth、barBarHeight、barFontSize：サイズの設定

payware_operations_get_transaction_status

ACTIVE な取引のステータスのみを取得します。完了済みまたは確定済みの取引には、履歴ツールを使用してください。

パラメーター：

• transactionId（必須）：取引 ID（pw で始まります）
• partnerId（必須）：パートナー ID
• privateKey（必須）：JWT 署名用の秘密鍵

payware_operations_simulate_callback

テスト用にコールバックのシナリオをシミュレートします。

パラメーター：

• transactionId（必須）：取引 ID
• status（任意）：CONFIRMED、DECLINED、FAILED、EXPIRED、または CANCELLED（デフォルト：CONFIRMED）
• callbackUrl（任意）：コールバックの送信先 URL
• amount（任意）：取引金額（デフォルト：10.00）
• currency（任意）：通貨（デフォルト：EUR）
• type（任意）：取引タイプ（デフォルト：PLAIN）

ユーティリティ

payware_generate_code_example

任意のpayware操作について、本番環境ですぐに使えるコード例を生成します。

パラメーター：

• operation（必須）：生成する操作。以下の一覧を参照してください
• language（任意）：python、nodejs、php、java、csharp、curl（デフォルト：python）
• partner_type（任意）：merchant、isv、payment_institution（デフォルト：merchant）
• include_comments（任意）：詳細なコードコメントを含めます（デフォルト：true）
• include_error_handling（任意）：包括的なエラー処理を含めます（デフォルト：true）

カテゴリー別の利用可能な操作：

認証：

• authentication - JWT認証のセットアップ

トランザクション操作（すべてのパートナータイプ）：

• create_transaction - 新しい決済トランザクションを作成
• get_transaction_status - トランザクションのステータスと詳細を取得
• process_transaction - 保留中のトランザクションを処理
• cancel_transaction - 保留中のトランザクションをキャンセル

商品操作（merchant、isv）：

• create_product - 新しい商品を作成
• get_product - 商品の詳細を取得
• list_products - すべての商品を一覧表示

POI操作（isv）：

• set_price - Point of Interactionデバイスに価格を設定
• cancel_price - POIで有効な価格をキャンセル
• get_poi - POIの詳細を取得
• get_poi_status - POIトランザクションのステータスを取得
• get_poi_qrcode - POI用のQRコードを生成
• list_pois - マーチャントのすべてのPOIを一覧表示

OAuth2操作（isvのみ）：

• obtain_token - OAuth2アクセストークンを取得
• get_token_info - OAuth2トークン情報を取得

データ操作（すべてのパートナータイプ）：

• generate_report - 分析レポートを生成
• get_report_status - レポート生成のステータスを取得

P2P操作（payment_institutionのみ）：

• initiate_p2p_transfer - ピアツーピア送金を開始
• accept_p2p_transfer - P2P送金を承認

サウンドバイト（payment_institutionのみ）：

• register_audio - サウンドバイトトランザクション用の音声コンテンツを登録

payware_generate_documentation

コード例を含む包括的なAPIドキュメントを生成します。

パラメーター：

• language（任意）：対象のプログラミング言語（デフォルト：python）
• partnerType（任意）：merchant、isv、payment_institution（デフォルト：merchant）
• includeScenarios（任意）：実際のインテグレーションシナリオを含めます（デフォルト：true）
• outputFormat（任意）：markdown、html、json（デフォルト：markdown）

payware_utils_format_request

SHA-256の一貫性を保つための決定論的なJSONシリアル化を使用して、APIリクエストを整形および検証します。

パラメーター：

• type（必須）：transaction、headers、またはcurl
• data（任意）：整形するデータ
• jwtToken（任意）：ヘッダー用のJWTトークン
• signature（任意）：リクエストの署名
• endpoint（任意）：curl用のAPIエンドポイント
• method（任意）：HTTPメソッド（デフォルト：POST）

payware_utils_format_json_deterministic

一貫したSHA-256計算のため、プロパティを決定論的な順序で並べてJSONを整形します。

パラメーター：

• data（必須）：シリアル化するオブジェクト
• minimize（任意）：空白を削除します（デフォルト：true）

payware_utils_server_info

MCPサーバーの情報と設定を取得します。

注： コンテンツハッシュの不一致エラーを防ぐため、すべてのトランザクションデータは一貫したプロパティ順序でシリアル化されます。

依存関係

• @modelcontextprotocol/sdk：MCPサーバーのフレームワーク
• axios：API呼び出し用のHTTPクライアント
• jsonwebtoken：JWTトークンの作成
• node-forge：RSA鍵の生成

環境

• サンドボックスのみ：すべてのAPI呼び出しはサンドボックス環境に制限されます
• ベースURL：https://sandbox.payware.eu/api/v1
• 対応通貨：EUR、USD、GBP
• 対応トランザクションタイプ：PLAIN、QR、BARCODE

セキュリティ

⚠️ 重要なセキュリティ上の注意：

環境変数

• 必須：すべての認証情報には環境変数を使用してください
• .envファイルをバージョン管理にコミットしないでください
• 開発環境と本番環境では異なる認証情報を使用してください
• 秘密鍵ファイルはウェブからアクセスできないディレクトリに保管してください

秘密鍵のセキュリティ

• サンドボックス環境用と本番環境用に、それぞれ別の鍵ペアを生成してください
• 秘密鍵はアクセス権限を制限したファイル権限（600）で保存してください
• 秘密鍵をソースコードに埋め込まないでください
• セキュリティポリシーに従って、定期的に鍵をローテーションしてください

API のセキュリティ

• このサーバーはサンドボックステスト専用に設計されています
• サンドボックス用の鍵を本番環境で使用しないでください
• 本番環境では適切なエラー処理を実装してください
• すべての API 通信で HTTPS を使用してください
• すべての入力パラメーターを検証してください
• レート制限と監視を実装してください

JSON のシリアライズと SHA-256 の一貫性

⚠️ 重大：payware API では、SHA-256 の計算に決定論的な JSON シリアライズが必要です

• プロパティの順序：JSON オブジェクトのプロパティは、一貫した順序にする必要があります
• 最小化形式：リクエスト本文には空白や整形を含めないでください
• SHA-256 の計算：API に送信するものと完全に同一の JSON 文字列から計算する必要があります
• 実装：このサーバーでは、一貫性を確保するために決定論的な JSON シリアライズを使用しています

正しい JSON 形式の例：

{"trData":{"amount":"25.50","currency":"EUR","reasonL1":"Payment description"},"trOptions":{"timeToLive":300,"type":"PLAIN"}}

重要な理由：

• プロパティの順序が異なると、SHA-256 ハッシュも異なります
• ハッシュが一致しない場合、ERR_INVALID_CONTENT_HASH エラーが発生します
• サーバーは、JWT の contentSha256 がリクエスト本文の SHA-256 と一致することを検証します

トラブルシューティング

よくある問題

1. 認証失敗（ERR_INVALID_SIGNATURE）

   • 根本原因：payware に登録された公開鍵が、秘密鍵と一致していません
   • 解決策：payware サイトに登録された公開鍵が、秘密鍵に対応していることを確認してください
   • 確認方法：openssl rsa -in privateKey.pem -pubout を使用して、秘密鍵から公開鍵を抽出します
   • ステータス：✅ 解決済み — 鍵は payware パートナーポータルに正しく登録する必要があります

2. コンテンツハッシュ不一致エラー（ERR_INVALID_CONTENT_HASH）

   • 根本原因：JSON プロパティの順序に一貫性がありません
   • 解決策：決定論的な JSON シリアライズを使用してください（このサーバーに実装済み）
   • 症状：サーバーログに、予想された SHA-256 ハッシュと実際の SHA-256 ハッシュの違いが表示されます
   • 予防策：常に /src/core/utils/json-serializer.js の createMinimizedJSON() を使用してください
   • ステータス：✅ 修正済み — 決定論的な JSON シリアライズを実装しました

3. トランザクションの作成に失敗する

   • 必須パラメーターがすべて指定されていることを確認してください
   • 金額が負の値でないことを確認してください
   • トランザクションタイプがサポートされていることを確認してください
   • ステータス：✅ 動作確認済み — 作成とキャンセルの操作が正常に機能することを確認しました

4. MCP 接続の問題

   • npm start でサーバーが起動していることを確認してください
   • MCP クライアントが正しく設定されていることを確認してください
   • stdio 通信をファイアウォールがブロックしていないことを確認してください
   • 注：デバッグには MCP Inspector（npm run inspector）を使用してください

プロキシツールとブリッジツール

HTTP プロキシサーバー（npm run proxy）：

• MCP ツールを HTTP REST API に接続します
• HTTP リクエストを使ったツールのテストに便利です
• ドキュメント：README-proxy.md

MCP ブリッジ（npm run bridge）：

• MCP サーバーを MCP Inspector に接続します
• デバッグと開発に不可欠です
• 次のコマンドと併用します：npm run inspector

テスト状況

✅ 動作確認済みの操作：

• RS256 アルゴリズムを使用した JWT トークンの作成
• トランザクションの作成（POST /api/transactions）
• トランザクションのキャンセル（PATCH /api/transactions/{id}）
• SHA-256 の一貫性を確保するための決定論的な JSON シリアライズ
• 公開鍵と秘密鍵のペアの検証

🧪 テスト結果：

• 実際の payware サンドボックス API を使用し、すべての MCP ツールのテストに成功しました
• トランザクションの作成とキャンセルの両方のフローが、エンドツーエンドで正常に動作しています
• 適切な鍵の登録により、署名の検証問題を解決しました

サポート

次の問題については：

• MCP サーバー：サーバーログと MCP クライアントの設定を確認してください
• payware API：payware のドキュメントとサンドボックスの状態を参照してください
• 統合：提供されているコード例と書式設定ツールを使用してください
• 鍵の問題：公開鍵が payware パートナーポータルに登録されていることを確認してください

ライセンス

MIT ライセンス