mcpField
M
mcp-nupay

mcp-nupay

本地服务
github.com/codespar金融数据2754 周前更新
代码仓库

关于 mcp-nupay

mcp-nupay 是 Nubank 商户收银服务 NuPay 的 MCP 服务，面向需要在巴西进行钱包结账的商户与 Agent。它支持通过 Pix 或 Nubank 应用确认付款，并提供预授权与循环扣款流程。

主要功能

  1. 01创建、查询与取消 NuPay 付款
  2. 02退款与退款状态查询
  3. 03收款方（最终受益人）登记与管理
  4. 04结算报告与分期付款条件查询
  5. 05CIBA / OTP 预授权与刷新令牌

适用场景

  1. 01为 Agent 发起 NuPay 结账并跟踪付款状态
  2. 02处理商户退款与结算对账
  3. 03为回头客配置预授权与循环扣款

MCP 相关

该项目为 MCP 服务，向 MCP 客户端暴露 22 个工具，用于付款、退款、收款方、结算及令牌管理。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "codespar-mcp-nupay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-nupay"
      ],
      "env": {
        "NUPAY_MERCHANT_KEY": "<NUPAY_MERCHANT_KEY>",
        "NUPAY_MERCHANT_TOKEN": "<NUPAY_MERCHANT_TOKEN>",
        "NUPAY_CLIENT_ID": "<NUPAY_CLIENT_ID>",
        "NUPAY_CLIENT_SECRET": "<NUPAY_CLIENT_SECRET>",
        "NUPAY_ENV": "<NUPAY_ENV>"
      }
    }
  }
}
启动命令npx -y @codespar/mcp-nupay
需要配置的环境变量
NUPAY_MERCHANT_KEY密钥NuPay X-Merchant-Key issued to your merchant
NUPAY_MERCHANT_TOKEN密钥NuPay X-Merchant-Token issued to your merchant
NUPAY_CLIENT_IDOAuth2/CIBA client_id for pre-authorized (recurrence) flows. Optional unless using backchannel_start / backchannel_complete.
NUPAY_CLIENT_SECRET密钥OAuth2/CIBA client_secret for pre-authorized flows. Optional unless using backchannel_* tools.
NUPAY_ENVsandbox | production. Defaults to sandbox. Drives both checkout API and auth base URLs.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@codespar/mcp-nupay0.2.2

工具

22

收录的工具列表 · 更新于 2 周前

参数类型必填说明
itemsarray是购买的商品明细
amountobject是付款金额对象
amount.valuenumber是以分为单位的金额（BRL）
amount.currencystring是ISO-4217，例如 BRL
shopperobject是客户身份信息
shopper.ipstring否用于欺诈评分的购物者 IP
shopper.namestring是
shopper.emailstring是
shopper.phonestring否
shopper.localestring否例如 pt-BR
shopper.documentstring是仅限 CPF 数字
shopper.documentTypeenum是CPF | CNPJ
shippingobject否配送地址和方式
storeNamestring否
recipientsarray否最多 10 位最终受益人（监管要求的拆分）
callbackUrlstring否用于状态通知的 HTTPS webhook URL
paymentFlowobject否用于重定向流程的返回／取消 URL
paymentFlow.cancelUrlstring否
paymentFlow.returnUrlstring否
referenceIdstring是电商支付参考 ID（每个商户内唯一）
installmentsnumber否分期次数（仅适用于预授权）
merchantNamestring否
paymentMethodobject是支付方式选择
paymentMethod.typestring是例如 NUPAY、PIX
paymentMethod.authorizationstring否NuPay 的授权模式（例如 CIBA、OTP、REDIRECT）
referenceDatestring否ISO-8601 时间戳
billingAddressobject否账单地址
delayToAutoCancelnumber否自动取消前的分钟数。默认值为 30。
merchantOrderReferencestring是商户侧订单 ID（每个商户内唯一）

详细介绍

@codespar/mcp-nupay

适用于 NuPay 的 MCP 服务 — Nubank 的商户结账通道。

NuPay 是 Nubank 面向巴西推出的 PayPal / Shop Pay 式方案：一种由钱包支持的结账方式，可借助 Nubank 在巴西超过 1 亿用户的覆盖范围。Agent 创建支付后，购物者可在 Nubank 应用中确认（推送通知 + 生物识别），也可通过 Pix 确认，资金随后结算给商户。预授权流程（CIBA / OTP）支持周期性付款，并为回头客实现真正的一键支付。

工具（22）

工具用途
create_payment创建 NuPay 结账支付。
get_payment按 pspReferenceId 获取完整支付详情（金额、购物者、商品、当前状态、时间戳）。
get_payment_status按 pspReferenceId 获取支付状态。
list_payments_by_date列出在指定日期范围内创建的支付。
cancel_payment取消尚未捕获/结算的支付。
create_refund退还已结算的支付（全额或部分退款）。
get_refund按 pspReferenceId + refundId 获取退款状态。
list_refunds列出针对指定支付发起的所有退款。
create_recipient注册最终受益人（监管要求的拆分付款必须提供）。
get_recipient按 referenceId 获取已注册的受益人。
update_recipient更新已注册的最终受益人（姓名、证件、国家/地区、类型）。
delete_recipient删除已注册的受益人。
list_recipients列出商户的已注册受益人（最终受益人）。
list_settlements列出指定日期范围内的结算报告（支付至商户银行账户的款项）。
get_settlement获取单笔结算（付款批次），包括其包含的交易列表。
query_payment_conditions查询指定金额可用的分期/支付条件，以及（可选）购物者 CPF。
create_preauth_payment使用预授权 Bearer access_token 创建 NuPay 支付（预授权/周期性付款流程）。
backchannel_start为购物者启动 CIBA / OTP 预授权。
backchannel_complete提交购物者收到的 OTP，完成 CIBA/OTP 流程。
backchannel_resend_otp向正在进行授权的票据对应的购物者重新发送 OTP。
exchange_token在 POST /v1/token 处兑换 authorization_code 或 refresh_token。
revoke_token在 POST /v1/token/revoke 处撤销已签发的 access_token 或 refresh_token。

安装

npm install @codespar/mcp-nupay

环境

NUPAY_MERCHANT_KEY="..."     # X-Merchant-Key issued to your merchant
NUPAY_MERCHANT_TOKEN="..."   # X-Merchant-Token (secret)
NUPAY_CLIENT_ID="..."        # Optional — OAuth client_id for pre-auth / recurrence
NUPAY_CLIENT_SECRET="..."    # Optional — OAuth client_secret
NUPAY_ENV="sandbox"          # sandbox (default) | production

身份验证

有两种流程：

  1. 标准商户 API（支付、退款、受益人、支付条件）使用 X-Merchant-Key + X-Merchant-Token 请求头。无需兑换令牌。
  2. 预授权/周期性付款使用 OAuth2 + CIBA / OTP。首先调用 backchannel_start，通过 backchannel_complete 验证，然后使用返回的 Bearer access_token 调用 create_preauth_payment。使用 exchange_token 刷新（grant_type=refresh_token）。访问令牌在 5 分钟后过期；周期性付款应长期存储刷新令牌。

基础 URL 根据 NUPAY_ENV 确定：

沙盒生产环境
APIhttps://sandbox-api.spinpay.com.brhttps://api.spinpay.com.br
身份验证https://sandbox-authentication.spinpay.com.br/apihttps://authentication.spinpay.com.br/api

JWT client_assertion 的签名由调用方负责 — exchange_token 需要传入已签名的断言，并设置 client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer。

运行

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

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

企业版

需要为 Agent 支付设置治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务之上增加了策略引擎、支付路由和合规模板。

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。