mcp-nupay

@codespar/mcp-nupay

Nupay 用の MCP サーバーです。Nubank の加盟店向け決済手段を提供します。

NuPay は、ブラジルにおける PayPal／Shop Pay に相当する Nubank の決済サービスです。Nubank のブラジル国内の 1 億人以上の顧客基盤を活用した、ウォレット連携型のチェックアウトを提供します。エージェントが決済を作成すると、購入者は Nubank アプリ内（プッシュ通知＋生体認証）または Pix で承認し、資金は加盟店に入金されます。事前承認フロー（CIBA／OTP）を利用すると、継続課金とリピーター向けの真のワンクリック決済が可能になります。

ツール（22）

ツール	目的
create_payment	NuPay のチェックアウト決済を作成します。
get_payment	pspReferenceId を指定して、決済の詳細（決済額、購入者、商品、現在のステータス、タイムスタンプ）を取得します。
get_payment_status	pspReferenceId を指定して、決済のステータスを取得します。
list_payments_by_date	指定した期間内に作成された決済の一覧を取得します。
cancel_payment	キャプチャまたは精算されていない決済をキャンセルします。
create_refund	精算済みの決済を返金します（全額または一部）。
get_refund	pspReferenceId と refundId を指定して、返金のステータスを取得します。
list_refunds	指定した決済に対して発行されたすべての返金を一覧表示します。
create_recipient	最終受益者を登録します（規制対象の分割決済に必須）。
get_recipient	referenceId を指定して、登録済みの受取人を取得します。
update_recipient	登録済みの最終受益者の情報（氏名、書類、国、種類）を更新します。
delete_recipient	登録済みの受取人を削除します。
list_recipients	加盟店に登録されている受取人（最終受益者）の一覧を取得します。
list_settlements	指定した期間内の精算レポート（加盟店の銀行口座への入金）を一覧表示します。
get_settlement	個別の精算（入金バッチ）を、対象となる取引の一覧とともに取得します。
query_payment_conditions	指定した金額と（任意で）購入者の CPF に対して利用可能な分割払い／決済条件を照会します。
create_preauth_payment	事前承認済みの Bearer access_token を使用して NuPay の決済を作成します（事前承認／継続課金フロー）。
backchannel_start	購入者の CIBA／OTP 事前承認を開始します。
backchannel_complete	購入者が受け取った OTP を送信して、CIBA／OTP フローを完了します。
backchannel_resend_otp	処理中の認証チケットについて、購入者に OTP を再送します。
exchange_token	POST /v1/token で authorization_code または refresh_token を交換します。
revoke_token	POST /v1/token/revoke で発行済みの access_token または refresh_token を無効化します。

インストール

npm install @codespar/mcp-nupay

環境

NUPAY_MERCHANT_KEY="..."     # X-Merchant-Key issued to your merchant
NUPAY_MERCHANT_TOKEN="..."   # X-Merchant-Token (secret)
NUPAY_CLIENT_ID="..."        # Optional — OAuth client_id for pre-auth / recurrence
NUPAY_CLIENT_SECRET="..."    # Optional — OAuth client_secret
NUPAY_ENV="sandbox"          # sandbox (default) | production

認証

フローは 2 種類あります。

1. 標準の加盟店 API（決済、返金、受取人、決済条件）では、X-Merchant-Key と X-Merchant-Token ヘッダーを使用します。トークン交換は不要です。
2. 事前承認／継続課金では、OAuth2 と CIBA／OTP を使用します。backchannel_start で開始し、backchannel_complete で検証してから、返された Bearer access_token を指定して create_preauth_payment を呼び出します。exchange_token（grant_type=refresh_token）で更新します。アクセストークンの有効期限は 5 分です。継続課金に備えて、リフレッシュトークンは長期間保管してください。

ベース URL は NUPAY_ENV から決まります。

	サンドボックス	本番環境
API	https://sandbox-api.spinpay.com.br	https://api.spinpay.com.br
認証	https://sandbox-authentication.spinpay.com.br/api	https://authentication.spinpay.com.br/api

JWT client_assertion の署名は呼び出し側で行う必要があります。exchange_token には、client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer を指定した、すでに署名済みのアサーションが必要です。

実行

# stdio (default)
npx @codespar/mcp-nupay

# HTTP
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-nupay

エンタープライズ

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

ライセンス

MIT