mcp-braspag

@codespar/mcp-braspag

Braspag 用の MCP サーバー — Cielo Group のエンタープライズ向けオーケストレーションレイヤーです。複数アクワイアラーへのルーティング、トークン保管庫（Cartão Protegido）、継続課金、マーケットプレイスでの売上分配、不正対策のオーケストレーションに対応します。

Braspag と Cielo（アクワイアラー）の違い

CodeSpar は、ビジネス契約が異なる Cielo Group のサーバーを2つ提供しています。

サーバー	製品	概要	利用者
@codespar/mcp-cielo	Cielo アクワイアラー	直接カード決済を処理する仕組み（クレジット、デビット、boleto、Pix）	Cielo 経由でカード決済を受け付けるすべての加盟店
@codespar/mcp-braspag（本サーバー）	Braspag / Pagador	あらゆるアクワイアラー上でのエンタープライズ向けオーケストレーション	ブラジルの大手小売企業（Magalu クラス）：複数アクワイアラーへのルーティング、トークン保管庫、マーケットプレイスでの売上分配

Braspag は、複数のアクワイアラーをまたいでオーケストレーションを行います。Cielo（または Rede、Stone）とのアクワイアリング契約はそのまま維持し、Braspag を重ねて利用することで、スマートルーティング、フェイルオーバー、カードを一度保管して複数のアクワイアラーで再利用する機能（Cartão Protegido）、継続課金の管理、マーケットプレイスの売上をサブマーチャント間で分配する機能を利用できます。

クイックスタート

Claude Desktop

~/.config/claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "braspag": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-braspag"],
      "env": {
        "BRASPAG_MERCHANT_ID": "your-merchant-uuid",
        "BRASPAG_MERCHANT_KEY": "your-merchant-key",
        "BRASPAG_ENV": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add braspag -- npx @codespar/mcp-braspag

Cursor / VS Code

.cursor/mcp.json または .vscode/mcp.json に追加します。

{
  "servers": {
    "braspag": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-braspag"],
      "env": {
        "BRASPAG_MERCHANT_ID": "your-merchant-uuid",
        "BRASPAG_MERCHANT_KEY": "your-merchant-key",
        "BRASPAG_ENV": "sandbox"
      }
    }
  }
}

ツール（22）

ツール	目的
create_sale	Braspag Transaction API で売上を作成します（POST /sales）。
capture_sale	事前承認済みの売上をキャプチャします（PUT /sales/{paymentId}/capture）。
void_sale	売上を無効化／キャンセルします（PUT /sales/{paymentId}/void）。
create_recurrent	継続課金のスケジュールを作成します（POST /recurrentPayments）。
disable_recurrent	継続課金を無効化します（PUT /recurrentPayments/{recurrentPaymentId}/Deactivate）。
update_recurrent_amount	継続課金の請求額を更新します（PUT /recurrentPayments/{recurrentPaymentId}/Amount）。
get_sale	PaymentId を指定して売上の詳細を取得します（GET /sales/{paymentId} — Query API）。
get_sale_by_order_id	MerchantOrderId を指定して売上を検索します（GET /sales?merchantOrderId=X — Query API）。
get_recurrent	継続課金の設定と履歴を取得します（GET /recurrentPayments/{recurrentPaymentId} — Query API）。
tokenize_card	カードを Braspag のトークン保管庫／Cartão Protegido にトークン化します（POST /card）。
get_card_token	Cartão Protegido のトークンに関連付けられた保存済みカード情報を取得します（GET /card/{token}）。
create_split_sale	マーケットプレイスの売上分配ルールを適用して売上を作成します（Payment.SplitPayments を指定して POST /sales）。
create_sale_3ds	3DS 認証済みのクレジットカード売上を作成します（POST /sales）。
create_zero_auth	0ドルのオーソリ／カードの有効性確認を行います（POST /zeroauth）。
create_boleto_sale	boleto の売上を作成する便利なラッパーです（Payment.Type=Boleto を指定して POST /sales）。
create_pix_sale	Pix の売上を作成する便利なラッパーです（Payment.Type=Pix を指定して POST /sales）。
reactivate_recurrent	以前に無効化した継続課金を再有効化します（PUT /recurrentPayments/{recurrentPaymentId}/Reactiva...
update_recurrent_next_payment	継続課金の NextPaymentDate を更新します（PUT /recurrentPayments/{recurrentPaymentId}/NextPaymentD...
update_recurrent_payment	継続課金スケジュールの Payment（CreditCard + Customer）を更新します（PUT /recurrentPayments/{recurrentPaymen...
create_antifraud_analysis	Braspag の不正対策オーケストレーション（Cyb...）を通じて、単独の不正分析を送信します（POST /fraudanalysis）。
delete_card_token	Cartão Protegido のトークンをトークン保管庫から削除します（DELETE /card/{token}）。
create_split_capture	事前承認済みの分配対象売上を、サブマーチャントごとの金額を上書きしてキャプチャします（PUT /sales/{paymentId}...

認証

Braspag では、Transaction API と Query API の両方で、MerchantId（UUID）と MerchantKey（シークレット）のヘッダーを使用します。

環境

環境	Transaction API	Query API
sandbox（デフォルト）	https://apisandbox.braspag.com.br/v2	https://apiquerysandbox.braspag.com.br/v2
production	https://api.braspag.com.br/v2	https://apiquery.braspag.com.br/v2

切り替えるには、BRASPAG_ENV=production を設定します。

認証情報の取得

1. Braspag Pagador を加盟店契約で有効にするため、Cielo / Braspag のアカウントチームにお問い合わせください。
2. MerchantId（UUID）と MerchantKey を受け取ります。
3. 以下の環境変数を設定します。

環境変数

変数	必須	説明
BRASPAG_MERCHANT_ID	はい	加盟店 UUID
BRASPAG_MERCHANT_KEY	はい	加盟店のシークレットキー
BRASPAG_ENV	いいえ	sandbox（デフォルト）または production

ロードマップ

v0.2（予定）

• create_sale_with_card_token — Cartão Protegido トークンを使用する便利なラッパー
• delete_card_token — 保管庫のトークンを失効させます
• get_sale_antifraud — Query API の不正対策詳細
• update_recurrent_payment — 定期決済の金額以外のフィールドを更新します
• create_zero_auth — カード検証用のゼロ円オーソリ

v0.3（予定）

• マーケットプレイス：サブ加盟店のオンボーディングエンドポイント
• 銀行振込票（boleto）の登録済み向けヘルパー
• Webhook 検証ヘルパー

貢献をご希望ですか？PR を作成するか、ツールをリクエストしてください。

リンク

• Braspag マニュアル（Pagador）
• Cielo / Braspag 開発者ポータル
• MCP Dev LATAM
• ランディングページ

エンタープライズ

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

ライセンス

MIT