mcp-rinne

@codespar/mcp-rinne

面向 Rinne 的 MCP 服务——巴西银行卡收单、PIX、银行业务和支付基础设施，涵盖完整的 API 功能

什么是 Rinne？

Rinne 是一个巴西支付基础设施 API。它采用 B2B2B 模式：你的 Organization 管理任意数量的 Merchants，每个商户通过 KYC 完成入驻，并通过 Affiliation 连接支付服务提供商（Rinne、Cappta、Celcoin 等），之后的所有操作都通过该关联完成，包括银行卡和 PIX 交易、已存储银行卡、3D Secure、提现/付款、账本和定价。

此 MCP 服务封装了整个 Rinne REST API，而不仅仅是银行卡收单，因此 AI Agent 可以在沙盒或生产环境中管理商户、执行交易、转移资金和管理访问权限。

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "rinne": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-rinne"],
      "env": {
        "RINNE_API_KEY": "your-api-key",
        "RINNE_SANDBOX": "true"
      }
    }
  }
}

Claude Code

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

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "rinne": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-rinne"],
      "env": {
        "RINNE_API_KEY": "your-api-key",
        "RINNE_SANDBOX": "true"
      }
    }
  }
}

工具（62）

公司

工具	用途
get_company	获取经过身份验证的公司（根据密钥范围，可能是组织或商户）
update_company	更新经过身份验证的公司

商户

工具	用途
create_merchant	在你的组织下创建商户（KYC）
list_merchants	列出商户
get_merchant	根据 ID 获取商户详情
update_merchant	更新商户

关联

工具	用途
create_affiliation	使用支付服务提供商（Rinne、Cappta、Celcoin 等）创建商户账户
register_affiliation	使用现有的服务提供商凭据注册网关模式的关联
list_affiliations	列出关联，可列出整个组织的关联或单个商户的关联
get_affiliation	获取特定关联

已存储银行卡

工具	用途
store_card	保存银行卡，以便在未来的交易中重复使用
list_cards	列出已存储的银行卡
get_card	根据 ID 获取已存储的银行卡
delete_card	删除已存储的银行卡

3D Secure

工具	用途
create_3ds_session	在交易前创建 3DS 身份验证会话

交易

工具	用途
create_transaction	创建银行卡交易（原始卡信息、已存储银行卡或 Apple Pay/Google Pay）或 PIX 交易
authenticate_transaction	为等待身份验证的交易完成 3DS
get_transaction	获取交易详情和状态，包括退款信息
list_transactions	列出交易，可列出整个组织的交易或单个商户的交易
cancel_transaction	取消待处理的交易（例如，未付款的 bolepix）
refund_transaction	全额或部分退款
cancel_refund	取消尚未结算的退款
get_transaction_receipt	获取交易收据（base64 PDF）
simulate_pay_transaction	仅限沙盒 — 将交易标记为已付款

PIX（收款密钥）

工具	用途
create_pix_collection_key	创建商户用于接收付款的 PIX 密钥
list_pix_collection_keys	列出商户的 PIX 收款密钥

账本

工具	用途
list_ledger_entries	列出经过身份验证的公司的账本条目
get_ledger_entry	获取单条账本条目

银行业务

工具	用途
create_bank_account	注册外部银行账户（收款目的地）
update_bank_account	将银行账户设为主账户
register_cashout_pix_key	注册外部 PIX 密钥作为收款目的地
get_balance	获取当前余额
topup_balance	仅限沙盒 — 模拟为余额充值
get_statement	获取指定日期范围内商户的余额对账单
create_internal_transfer	在组织自己的银行账户之间转账
list_judicial_blockages	列出影响余额的法院命令账户冻结

取款

工具	用途
create_cashout	向银行账户或 PIX 密钥发起收款
list_cashouts	列出取款
get_cashout	获取单笔取款
get_cashout_receipt	获取取款的收据

定价

工具	用途
list_fee_policies	列出费用政策（向商户收取的费用）
create_fee_policy	创建费用政策
replace_fee_policy	完整替换费用政策
update_fee_policy	部分更新费用政策
list_cost_policies	列出成本政策（服务提供商向你收取的费用）
list_mccs	列出商户类别代码

Webhook

工具	用途
get_webhook_dashboard_url	获取用于配置 webhook 端点／事件的 URL

系统

工具	用途
get_health	检查 API 健康状态

访问管理 — 需要 JWT

工具	用途
create_api_key	创建 API 密钥（仅显示一次）
list_api_keys	列出 API 密钥（仅显示前缀和末 4 位）
revoke_api_key	撤销 API 密钥
create_role	创建自定义角色
list_roles	列出角色
list_permissions	列出所有可用权限
get_current_session	查看 JWT 会话的当前用户身份

用户

工具	用途
create_user	创建用户（商户范围：x-api-key；组织范围：JWT）
list_users	列出用户
update_user	更新用户的姓名／角色 — 仅限 JWT、组织范围
suspend_user	暂停用户 — 仅限 JWT、组织范围
activate_user	重新激活用户 — 仅限 JWT、组织范围

邮政编码 — 需要 JWT

工具	用途
lookup_zipcode	根据 CEP 查询巴西地址

沙盒

工具	用途
get_sandbox_guide	返回测试卡、基于金额的拒绝规则，以及需要 JWT 的工具

卡片数据绝不会以明文发送

Rinne 不接受通过此 API 传入的原始卡号或 CVV。每个 number／cvv 字段（以及 Apple Pay／Google Pay 的 network_token／cryptogram）都必须是由浏览器中运行的 rinne-js Card/Wallet Element 生成的加密令牌（"ev:..."）；原始 PAN／CVV 会被拒绝，并返回 400 VALIDATION_ERROR，且不提供服务端加密方式。

实际上，此服务是结账流程的后半部分：运行 rinne-js 流程（参见 rinne-js 文档），在客户端收集并加密卡片，然后将生成的令牌传给此处的 store_card 或 create_transaction 以完成操作。或者，在 create_transaction 中使用 card_id，对通过 store_card 保存的卡片收费。

组织范围与商户范围

所有处理交易、卡片、3DS 会话、关联关系或银行业务的资源都接受可选的 merchant_id：

• 省略 — 在组织／自身范围内操作。
• 提供 — 针对指定商户操作（/v1/merchants/{merchant_id}/...），适用于管理多个商户的组织。

refund_transaction、get_statement 和 create_pix_collection_key／list_pix_collection_keys 始终需要 merchant_id — 它们仅存在于商户范围内。

两种 PIX 密钥资源——不要混淆

Rinne 有两种不同的 PIX 密钥资源，其端点名称相似：

• create_pix_collection_key（/v1/merchants/{id}/pix/keys）——商户用于接收 PIX 付款的密钥，与服务提供商关联（provider、key_type）。
• register_cashout_pix_key（/v1/merchants/{id}/pix-keys 或 /v1/companies/me/pix-keys）——注册为提现付款目的地的外部密钥（key、primary）。

身份验证

API 的大部分功能使用 x-api-key，但 Rinne 的访问管理接口有意拒绝使用该方式——泄露的 API 密钥不得用于创建其他密钥、角色或用户。这些工具需要 JWT 会话：

身份验证	使用方
x-api-key（RINNE_API_KEY）	其他所有功能——商户、服务商关联、卡片、3DS、交易、PIX、银行业务、提现、定价、Webhook、商户范围内的用户
JWT（RINNE_EMAIL + RINNE_PASSWORD）	create_api_key、list_api_keys、revoke_api_key、create_role、list_roles、list_permissions、get_current_session、lookup_zipcode，以及组织范围内的 create_user/list_users/update_user/suspend_user/activate_user

此服务会在首次调用受 JWT 限制的工具时延迟登录并缓存令牌；收到 401 时会重新登录一次。如果设置了 RINNE_COMPANY_ID，服务会在登录后立即选择该公司（适用于可访问多家公司的账户）。如果未设置 RINNE_EMAIL/RINNE_PASSWORD，受 JWT 限制的工具会返回明确错误，而不会静默失败——服务的其他功能仍可正常使用。

沙盒 / 测试

默认使用沙盒（https://api-sandbox.rinne.com.br/core）。设置 RINNE_SANDBOX=false 可切换到生产环境（https://api.rinne.com.br/core）。

沙盒模拟规则

调用 get_sandbox_guide 查看完整 JSON，或参见下文：

测试卡片

卡号	品牌	3DS
5155901222280001	Mastercard	否
4012001037141112	Visa	否
4242424242424242	Visa	挑战

按金额确定结果

金额（以分为单位）的最后两位数字决定结果，而不是卡号：

最后两位数字	结果
00	已批准
51	已拒绝——余额不足
05	已拒绝——不予承兑
54	已拒绝——卡片已过期

示例：amount: 1051 → REFUSED，代码为 51。

PIX

使用 simulate_pay_transaction（仅限沙盒）将状态为 WAITING_PAYMENT 的 PIX 交易标记为已付款。

参考：Rinne 测试指南

环境变量

变量	必填	说明
RINNE_API_KEY	是	API 密钥，以 x-api-key 发送
RINNE_SANDBOX	否	默认为沙盒；设置为 "false" 可切换到生产环境
RINNE_EMAIL	否	受 JWT 限制的工具所用登录标识符
RINNE_PASSWORD	否	登录密码，与 RINNE_EMAIL 配合使用
RINNE_COMPANY_ID	否	登录后要选择的公司，适用于多公司账户

链接

• Rinne 文档
• rinne-js SDK
• MCP Dev LATAM
• 落地页

企业版

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

许可证

MIT