mcp-transbank

@codespar/mcp-transbank

Transbank 向けの MCP サーバー — チリ最大のカードアクワイアラーです。

Transbank はチリの商取引で事実上の標準です（国営企業を起源とし、チリの銀行コンソーシアムが所有しています）。チリを含めて「CodeSpar はラテンアメリカをカバーしている」と主張するには、このサーバーの提供が不可欠です。

以下の 2 つの製品に対応しています。

• Webpay Plus — 1 回限りのリダイレクト決済です（buy_order + amount。ユーザーは Webpay にリダイレクトされて支払います）。
• Webpay OneClick Mall — 複数の加盟店コードに分割できる、トークン化された継続課金／カード・オン・ファイル決済です（「モール」モデル）。

ツール（19）

ツール	用途
webpay_create_transaction	Webpay Plus の取引を作成します。
webpay_commit_transaction	ユーザーが Webpay のフローから戻った後、Webpay Plus の取引を確定します。
webpay_get_transaction_status	トークンを使って、Webpay Plus の取引の現在のステータスを取得します。
webpay_refund_transaction	確定済みの Webpay Plus の取引を返金します。
webpay_increase_amount	以前に承認された Webpay Plus の取引を売上計上します（一部売上計上／遅延売上計上フロー）。
webpay_capture_transaction	以前に承認された Webpay Plus の取引を遅延売上計上します。
webpay_mall_create_transaction	Webpay Mall の取引を作成します。1 つの親 buy_order を複数の販売者の加盟店コードに分割します。
webpay_mall_commit_transaction	ユーザーが戻った後、Webpay Mall の取引を確定します。
webpay_mall_get_transaction_status	トークンを使って Webpay Mall の取引のステータスを取得します（子取引ごとの詳細を含みます）。
webpay_mall_refund_transaction	Webpay Mall の取引に含まれる子販売者 1 件分を返金します。
webpay_mall_capture_transaction	Webpay Mall の取引に含まれる子販売者 1 件分を遅延売上計上します。
oneclick_create_inscription	OneClick Mall のカード登録フローを開始します。
oneclick_finish_inscription	ユーザーが戻った後、OneClick Mall の登録を完了します。
oneclick_delete_inscription	ユーザーの保存済み OneClick Mall カードを削除（登録解除）します。
oneclick_authorize	1 つ以上のモール加盟店コードで、保存済み OneClick Mall カードに請求します。
oneclick_capture	以前に承認された OneClick Mall の請求を売上計上します（遅延売上計上フロー）。
oneclick_refund	OneClick Mall の請求を返金します。
oneclick_status	親 buy_order を使って OneClick Mall の取引のステータスを取得します。
oneclick_get_transaction_by_buy_order	親 buy_order を使って OneClick Mall の取引を検索します。

インストール

npm install @codespar/mcp-transbank@alpha

環境

TRANSBANK_COMMERCE_CODE="..."   # merchant commerce code (Tbk-Api-Key-Id)
TRANSBANK_API_KEY_SECRET="..."  # secret key (Tbk-Api-Key-Secret)
TRANSBANK_ENV="integration"     # 'integration' (default) or 'production'

インテグレーションのベース URL：https://webpay3gint.transbank.cl 本番環境のベース URL：https://webpay3g.transbank.cl

認証

すべてのリクエストで、次の 2 つのヘッダーを送信します。

Tbk-Api-Key-Id: <commerce_code>
Tbk-Api-Key-Secret: <api_key_secret>
Content-Type: application/json

サーバーがヘッダーを自動的に処理するため、設定するのは環境変数だけです。

実行

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

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

Webpay Plus のフロー

1. buy_order、session_id、amount、return_url を指定して webpay_create_transaction を呼び出します。
2. ユーザーを url?token_ws=<token> にリダイレクトします。
3. ユーザーは Webpay で支払い、return_url にリダイレクトされます。
4. 戻されたトークンを指定して webpay_commit_transaction を呼び出し、実際に請求します。

OneClick Mall のフロー

1. username、email、response_url を指定して oneclick_create_inscription を呼び出します。ユーザーを url_webpay にリダイレクトします。
2. ユーザーが戻ったら、oneclick_finish_inscription を呼び出します。戻された tbk_user をユーザーに紐付けて保存します。
3. 後で請求するには、username、tbk_user、親モールの buy_order、および details 配列（子加盟店ごとに 1 件）を指定して oneclick_authorize を呼び出します。

エンタープライズ

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

ライセンス

MIT