mcp-picpay

@codespar/mcp-picpay

PicPay Business 向けの MCP サーバーです。PicPay は、6,000 万人以上のユーザーを持つブラジルのデジタルウォレットです。

PicPay の Checkout API を使用すると、加盟店は支払いインテントを作成できます。購入者は PicPay アプリ内で支払いを完了し、リダイレクト URL と Pix 形式の QR コードを受け取ります。Recurrency API を使用すると、サブスクリプションプランも追加できます。

ツール（20）

ツール	目的
create_payment	PicPay のチェックアウト支払いを作成します。
get_payment_status	referenceId で支払いのステータスを取得します。
cancel_payment	PicPay の注文をキャンセルします。
create_plan	サブスクリプションプランを作成します（Recurrency API）。
list_plans	この加盟店に登録されているすべてのサブスクリプションプランを一覧表示します。
update_plan	既存のサブスクリプションプランを更新します。
delete_plan	サブスクリプションプランを削除します。
create_subscription	購入者をサブスクリプションプランに登録します。
get_subscription	ID でサブスクリプションを取得します。
cancel_subscription	有効なサブスクリプションをキャンセルします。
validate_notification	受信した webhook コールバックが PicPay からのものであることを、x-seller-token ヘッダーを PI... と比較して確認します。
refund_payment	支払い済みの PicPay 注文を、必要に応じて一部返金します。
create_b2p_transfer	Business-to-Person（B2P）送金を作成します。加盟店のウォレットから、PicPay ユーザーとして識別される受取人に資金を送金します...
get_b2p_transfer	referenceId で B2P 送金のステータスを取得します。
create_batch_payment	1 回のリクエストで複数の B2P 送金を送信します。
list_transactions	期間を指定して、加盟店の取引（支払いと送金）を一覧表示します。
get_wallet_balance	加盟店の現在の PicPay ウォレット残高（BRL 建ての利用可能額とブロック額）を取得します。
generate_static_qrcode	店舗内での利用や繰り返し利用に向けて、静的な PicPay Pay QR コードを生成します。
generate_dynamic_qrcode	金額を固定し、必要に応じて有効期限を指定して、動的な PicPay Pay QR コードを生成します。
create_payment_link	共有可能な PicPay 支払いリンクを作成します。

インストール

npm install @codespar/mcp-picpay@alpha

環境

PICPAY_TOKEN="..."          # Merchant integration token (x-picpay-token header)
PICPAY_SELLER_TOKEN="..."   # Seller token used to validate webhook callbacks
PICPAY_BASE_URL="..."       # Optional. Defaults to https://appws.picpay.com/ecommerce/public

認証

すべてのリクエストで次の情報を送信します。

Content-Type: application/json
x-picpay-token: <PICPAY_TOKEN>

PicPay の webhook コールバックには x-seller-token: <PICPAY_SELLER_TOKEN> が含まれます。ペイロードを信頼する前に、validate_notification ツールを使用するか、自身でヘッダーを照合してください。その後、get_payment_status で正式なステータスを取得します。

実行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-picpay

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-picpay

ステータス

0.1.0-alpha.1。主要なチェックアウトエンドポイント（/payments、/payments/{ref}/status、/payments/{ref}/cancellations）は、PicPay の公開ドキュメントに照らして検証済みです。Recurrency（プランとサブスクリプション）のエンドポイントは、ドキュメントに記載されたパスの形式に基づいていますが、本番環境で使用する前に、フィールドレベルのスキーマ（frequency の列挙値、サブスクリプションのレスポンス）を実際の API で確認してください。

エンタープライズ

エージェントによる支払いに、ガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、支払いルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT