mcp-safrapay

@codespar/mcp-safrapay

面向 Safrapay 的 MCP 服务——Banco Safra 的收单机构。专注于巴西中大型商户及私人银行客户，跨足 B2B 银行业务。

Safrapay 的 API 由 Aditum 支付平台提供（文档见 safrapay-docs.aditum.com.br）。网关、门户、对账和 Webhook 产品分别部署在不同的基础域名下。

状态：0.1.0-alpha.1。 此处的端点路径依据 Aditum 托管的 Safrapay 开发者文档（可公开访问）整理。身份验证流程（网关使用 BCRYPT + CNPJ，之后使用 JWT Bearer）是尽力推断的：公开文档未完整说明 BCRYPT 哈希输入格式，很可能需要沙盒账户才能最终确定。在通过真实沙盒商户验证之前，请将所有工具视为脚手架。

工具（22）

工具	用途
authorize_payment	在 Safrapay 上授权信用卡付款。
capture_payment	捕获之前已授权（预授权）的付款。
cancel_payment	取消（撤销）已授权但尚未捕获的付款。
refund_payment	退还已捕获的付款。
create_pix	创建 Pix 收款。
create_boleto	创建 boleto 收款。
get_payment	根据 Safrapay chargeId 检索收款。
tokenize_card	将卡片令牌化，以便安全地重复使用，符合 PCI 要求。
create_split_rule	为现有收款配置分账分配规则。
get_statement	检索电子账单（extrato）。
list_transactions	列出收款，可选添加筛选条件。
delete_card_token	撤销已存储的卡片令牌。
search_by_merchant_order	根据商户侧订单标识符（创建时提供的 order_id）查找收款。
query_chargeback	检索某笔收款的拒付（contestacao）详情：原因代码、收单机构截止日期、争议金额、证据……
query_installments	模拟指定金额的分期付款方案。
authenticate_3ds	在调用 authorize_payment 前启动 3-D Secure 身份验证。
create_recurrence	创建定期计费订阅。
get_recurrence	根据 id 检索定期扣款信息：计划、下次扣款日期、扣款历史和状态。
cancel_recurrence	取消有效的定期扣款。
get_settlement_report	从对账主机检索结算（liquidacao）报告。
create_payment_link	创建托管结账付款链接。
register_webhook	在 Safrapay Webhook 产品上批量注册订阅。

安装

npm install @codespar/mcp-safrapay@alpha

环境

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'

基础 URL

Safrapay 将 API 拆分为四个部署在不同域名下的产品：

产品	沙盒	生产环境
网关（付款）	https://payment-dev.aditum.com.br	https://payment.aditum.com.br
门户（管理）	https://portal-dev.aditum.com.br	https://portal-api.aditum.com.br
对账	https://reconciliation-dev.aditum.com.br	https://reconciliation-api.aditum.com.br
Webhook	https://webhook-dev.aditum.com.br	https://webhook.aditum.com.br

身份验证

网关采用两步引导流程：

1. 向 POST {gateway}/v2/merchant/auth 发送请求，携带请求头 Authorization: <BCRYPT(CNPJ+MerchantToken)> 和 merchantCredential: <CNPJ>，以换取 JWT 访问令牌。
2. 后续调用均发送 Authorization: Bearer <jwt>。

服务会在内存中缓存 JWT，直到令牌过期前 60 s。BCRYPT 输入拼接方式是有根据的推测；获得沙盒账户后请进一步确认。

运行

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

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

端点映射（供工具使用）

工具	方法	路径（除非另有说明，否则位于网关下）
authorize_payment	POST	/v2/charge/authorization 或 /v2/charge/preauthorization
capture_payment	PUT	/v2/charge/capture/{chargeId}
cancel_payment	PUT	/v2/charge/cancelation/{chargeId}
refund_payment	PUT	/v2/charge/cancelation/{chargeId}（部分金额）
create_pix	POST	/v2/charge/pix
create_boleto	POST	/v2/charge/boleto
get_payment	GET	/v2/charge/{chargeId}
tokenize_card	POST	/v2/card（或 /v2/temporary/card）
create_split_rule	PUT	/v2/charge/split/{chargeId}
get_statement	GET	/v2/Account/Movement/Extract
list_transactions	GET	/v2/charges
register_webhook	POST	{webhook}/v1/webhook/bulk

企业版

需要为 Agent 付款设置治理机制、预算限制和审计追踪？CodeSpar Enterprise 在这些 MCP 服务的基础上，增加了策略引擎、付款路由和合规模板。

许可证

MIT