mcp-braspag

@codespar/mcp-braspag

面向 Braspag 的 MCP 服务——Cielo Group 的企业级编排层：多收单机构路由、令牌库（Cartão Protegido）、定期付款、市场平台分账、反欺诈编排。

Braspag 与 Cielo（收单机构）的区别

CodeSpar 提供 两个 Cielo Group 服务，业务合约各不相同：

服务	产品	说明	使用者
@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	创建带有市场平台分账规则的销售（POST /sales，包含 Payment.SplitPayments）。
create_sale_3ds	创建经过 3DS 身份验证的信用卡销售（POST /sales）。
create_zero_auth	零金额授权 / 银行卡验证（POST /zeroauth）。
create_boleto_sale	便捷封装，用于创建 boleto 销售（POST /sales，Payment.Type=Boleto）。
create_pix_sale	便捷封装，用于创建 Pix 销售（POST /sales，Payment.Type=Pix）。
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 的反欺诈编排提交独立的反欺诈分析（POST /fraudanalysis）（Cyb...
delete_card_token	删除 Cartão Protegido 令牌库令牌（DELETE /card/{token}）。
create_split_capture	捕获先前已授权的分账销售，并覆盖各子商户的金额（PUT /sales/{paymentId}...

身份验证

Braspag 在交易 API 和查询 API 中均使用 MerchantId（UUID）和 MerchantKey（密钥）标头。

环境

环境	交易 API	查询 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. 联系 Cielo / Braspag 客户团队，在您的商户合同中启用 Braspag Pagador。
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 — 查询 API 反欺诈详情
• update_recurrent_payment — 更新定期付款中的非金额字段
• create_zero_auth — 用于验证卡片的零金额授权

v0.3（计划中）

• Marketplace：子商户入驻端点
• 银行付款单（boleto）仅注册辅助工具
• Webhook 验证辅助工具

想要贡献？提交 PR 或申请工具。

链接

• Braspag 手册（Pagador）
• Cielo / Braspag 开发者门户
• MCP Dev LATAM
• 产品介绍页

企业版

需要为由 Agent 驱动的 Braspag 付款提供治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务基础上增加了策略引擎、支付路由和合规模板。

许可证

MIT