Mcp Safrapay

io.github.codespar由 GitHub 账号 codespar 发布v0.2.0-alpha.3更新于 Oct 24, 2026

MCP server for Safrapay — Banco Safra acquirer: credit, Pix, boleto + split, 3DS, chargebacks

已验证STDIO仅桌面金融商业与电商

概览

AI 生成的概览

面向 Safrapay（Banco Safra 收单机构）的本地 MCP 服务器，让助手创建和管理信用卡、Pix、boleto 收款、退款、分账、订阅与对账查询。

可以做什么
授权、捕获、取消和退款信用卡支付，并在授权前完成 3-D Secure 认证。创建 Pix 与 boleto 收款、支付链接、分账规则和循环扣款订阅，并可取消订阅。按 chargeId 或商户订单号查询收款、列出交易、模拟分期，获取对账单和结算报告。对卡片进行令牌化、撤销已存卡令牌、查询拒付详情，并批量注册 webhook。
适用场景
适合使用 Safrapay/Aditum 支付的巴西商户或开发者，希望由助手完成收款创建、退款、对账查询或 webhook 配置。目前为早期 alpha 版本，更适合在沙箱中试验，而非用于真实支付操作。
运行要求
以 npm 包形式在本地运行（需要 Node.js），默认使用 stdio，设置 MCP_HTTP 后可通过 HTTP 运行。需要 SAFRAPAY_CLIENT_ID（商户 CNPJ）、SAFRAPAY_CLIENT_SECRET（商户令牌）、SAFRAPAY_MERCHANT_ID，以及可选的 SAFRAPAY_ENV（默认 sandbox）。需要能访问 Aditum 托管的 Safrapay 各主机。
安装前请注意
涉及真实支付凭据：SAFRAPAY_CLIENT_SECRET 是用于计算认证头的商户令牌，切勿写入日志。相关工具会动钱和改数据——授权、捕获、退款、取消、创建收款与订阅、撤销卡令牌、注册 webhook。README 说明认证流程与接口路径尚未验证，属于推测，请先在沙箱测试，验证前不要用于生产。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Safrapay，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@codespar/mcp-safrapay

MCP server for Safrapay — Banco Safra's acquirer. B2B-banking crossover focused on mid-to-large BR merchants and private-banking clientele.

Safrapay's API surface is operated on Aditum's payment platform (documented at safrapay-docs.aditum.com.br). The gateway, portal, reconciliation, and webhook products are split across separate base hosts.

Status: 0.1.0-alpha.1. The endpoint paths here were derived from the Aditum-hosted Safrapay developer docs (publicly reachable). Auth flow (BCRYPT + CNPJ on gateway, JWT Bearer thereafter) is best-effort: the BCRYPT hash input format is not fully specified in public docs and very likely requires a sandbox account to finalize. Treat all tools as scaffolding until validated against a live sandbox merchant.

Tools (22)

ToolPurpose
authorize_paymentAuthorize a credit-card payment on Safrapay.
capture_paymentCapture a previously authorized (pre-auth) payment.
cancel_paymentCancel (void) an authorized-but-uncaptured payment.
refund_paymentRefund a captured payment.
create_pixCreate a Pix charge.
create_boletoCreate a boleto charge.
get_paymentRetrieve a charge by Safrapay chargeId.
tokenize_cardTokenize a card for PCI-safe reuse.
create_split_ruleConfigure split distribution for an existing charge.
get_statementRetrieve the digital statement (extrato).
list_transactionsList charges with optional filters.
delete_card_tokenRevoke a stored card token.
search_by_merchant_orderLook up charges by the merchant-side order identifier (the order_id supplied at creation).
query_chargebackRetrieve chargeback (contestacao) detail for a charge: reason code, acquirer deadline, dispute amount, evid...
query_installmentsSimulate an installment plan for a given amount.
authenticate_3dsKick off 3-D Secure authentication before authorize_payment.
create_recurrenceCreate a recurring-billing subscription.
get_recurrenceRetrieve a recurrence by id: schedule, next-charge date, charge history, status.
cancel_recurrenceCancel an active recurrence.
get_settlement_reportRetrieve a settlement (liquidacao) report from the reconciliation host.
create_payment_linkCreate a hosted-checkout payment link.
register_webhookBulk-register webhook subscriptions on the Safrapay webhook product.

Install

bash
npm install @codespar/mcp-safrapay@alpha

Environment

bash
SAFRAPAY_CLIENT_ID="..."      # Merchant CNPJ (sent as merchantCredential)SAFRAPAY_CLIENT_SECRET="..."  # MerchantToken (used to compute BCRYPT)SAFRAPAY_MERCHANT_ID="..."    # Safrapay merchant id (body field where required)SAFRAPAY_ENV="sandbox"        # 'sandbox' (default) or 'production'

Base URLs

Safrapay splits its API into four products hosted on distinct domains:

ProductSandboxProduction
Gateway (payments)https://payment-dev.aditum.com.brhttps://payment.aditum.com.br
Portal (management)https://portal-dev.aditum.com.brhttps://portal-api.aditum.com.br
Reconciliationhttps://reconciliation-dev.aditum.com.brhttps://reconciliation-api.aditum.com.br
Webhookhttps://webhook-dev.aditum.com.brhttps://webhook.aditum.com.br

Authentication

Gateway uses a two-step bootstrap:

  1. POST {gateway}/v2/merchant/auth with headers Authorization: <BCRYPT(CNPJ+MerchantToken)> and merchantCredential: <CNPJ> to exchange for a JWT access token.
  2. Subsequent calls send Authorization: Bearer <jwt>.

The server caches the JWT in memory until 60 s before expiry. The BCRYPT input concatenation is an informed guess; refine once you have a sandbox account.

Run

bash
# stdio (default)npx @codespar/mcp-safrapay
# HTTPMCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-safrapay

Endpoint map (used by tools)

ToolMethodPath (under gateway, unless noted)
authorize_paymentPOST/v2/charge/authorization or /v2/charge/preauthorization
capture_paymentPUT/v2/charge/capture/{chargeId}
cancel_paymentPUT/v2/charge/cancelation/{chargeId}
refund_paymentPUT/v2/charge/cancelation/{chargeId} (partial amount)
create_pixPOST/v2/charge/pix
create_boletoPOST/v2/charge/boleto
get_paymentGET/v2/charge/{chargeId}
tokenize_cardPOST/v2/card (or /v2/temporary/card)
create_split_rulePUT/v2/charge/split/{chargeId}
get_statementGET/v2/Account/Movement/Extract
list_transactionsGET/v2/charges
register_webhookPOST{webhook}/v1/webhook/bulk

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT

来源：packages/payments/safrapay/README.md，提交 d0a519a

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.2.0-alpha.3最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分