Mcp Nupay

io.github.codespar由 GitHub 账号 codespar 发布v0.2.2更新于 Oct 24, 2026

MCP server for NuPay — Nubank merchant checkout: Pix + wallet one-click for 100M+ BR users

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

概览

AI 生成的概览

NuPay（Nubank 巴西商户结账）的 MCP 服务器，让助手创建、查询、取消和退款支付，并管理结算与收款人。

可以做什么
  • 创建、查询、按日期列出并取消 NuPay 结账支付，按参考号查看支付状态。
  • 发起全额或部分退款，查询退款状态与某笔支付的全部退款。
  • 注册、更新、删除和列出最终收款人（分账所需）。
  • 列出结算报告，查看单笔结算批次及其包含的交易。
  • 按金额（可选带购物者 CPF）查询分期与支付条件。
  • 执行预授权与复购流程：发起并完成 CIBA/OTP 授权、重发 OTP、创建预授权支付，以及换取或撤销 OAuth 令牌。
适用场景
适合需要为巴西客户操作 NuPay 商户账户的场景：收款结账、处理退款、跟踪结算，或为回头客搭建一键支付与定期扣款流程。
运行要求
通过 npm 包以 stdio 在本地运行（需 Node.js），设置 MCP_HTTP 与 MCP_PORT 时也可走 HTTP。需要 NUPAY_MERCHANT_KEY 与 NUPAY_MERCHANT_TOKEN；仅在使用 backchannel 预授权工具时才需要 NUPAY_CLIENT_ID 与 NUPAY_CLIENT_SECRET。NUPAY_ENV 选择 sandbox（默认）或 production，并决定 API 与认证的基础地址。需要能访问 NuPay/Spinpay 的网络。
安装前请注意
该服务器会动真金白银：可创建支付、发起退款、取消支付、删除收款人、撤销令牌。NUPAY_MERCHANT_TOKEN 与 NUPAY_CLIENT_SECRET 是商户密钥，须妥善保管。NUPAY_ENV 默认 sandbox，但改为 production 后同一批工具会指向线上接口。预授权流程涉及购物者 OTP 与长期保存的 refresh token，客户端断言需自行签名。支付与购物者数据（含 CPF）会发送给 NuPay/Spinpay。

安装

在 SourceWeft 中

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

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

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@codespar/mcp-nupay

MCP server for NuPay — Nubank's merchant checkout rail.

NuPay is Nubank's answer to PayPal / Shop Pay for Brazil: a wallet-backed checkout that leverages Nubank's 100M+ BR customer distribution. Agents create a payment, the shopper confirms inside the Nubank app (push + biometric) or via Pix, and funds settle to the merchant. Pre-authorized flows (CIBA / OTP) unlock recurrence and true one-click for repeat buyers.

Tools (22)

ToolPurpose
create_paymentCreate a NuPay checkout payment.
get_paymentRetrieve full payment details (amount, shopper, items, current status, timestamps) by pspReferenceId.
get_payment_statusRetrieve a payment's status by pspReferenceId.
list_payments_by_dateList payments created within a date range.
cancel_paymentCancel a payment that has not yet been captured/settled.
create_refundRefund a settled payment (full or partial).
get_refundRetrieve refund status by pspReferenceId + refundId.
list_refundsList all refunds issued against a given payment.
create_recipientRegister a final beneficiary (required for regulatory split payments).
get_recipientRetrieve a registered recipient by referenceId.
update_recipientUpdate a registered final beneficiary (name, document, country, type).
delete_recipientRemove a registered recipient.
list_recipientsList registered recipients (final beneficiaries) for the merchant.
list_settlementsList settlement reports (payouts to the merchant bank account) within a date range.
get_settlementRetrieve a single settlement (payout batch) including the list of underlying transactions.
query_payment_conditionsQuery available installment/payment conditions for a given amount and (optionally) shopper CPF.
create_preauth_paymentCreate a NuPay payment using a pre-authorized Bearer access_token (pre-auth / recurrence flow).
backchannel_startStart a CIBA / OTP pre-authorization for a shopper.
backchannel_completeComplete a CIBA/OTP flow by submitting the OTP the shopper received.
backchannel_resend_otpResend the OTP to the shopper for an in-flight authorization ticket.
exchange_tokenExchange an authorization_code or refresh_token at POST /v1/token.
revoke_tokenRevoke an issued access_token or refresh_token at POST /v1/token/revoke.

Install

bash
npm install @codespar/mcp-nupay

Environment

bash
NUPAY_MERCHANT_KEY="..."     # X-Merchant-Key issued to your merchantNUPAY_MERCHANT_TOKEN="..."   # X-Merchant-Token (secret)NUPAY_CLIENT_ID="..."        # Optional — OAuth client_id for pre-auth / recurrenceNUPAY_CLIENT_SECRET="..."    # Optional — OAuth client_secretNUPAY_ENV="sandbox"          # sandbox (default) | production

Authentication

Two flows:

  1. Standard merchant API (payments, refunds, recipients, payment-conditions) uses X-Merchant-Key + X-Merchant-Token headers. No token exchange.
  2. Pre-authorized / recurrence uses OAuth2 + CIBA / OTP. Start with backchannel_start, validate via backchannel_complete, then call create_preauth_payment with the returned Bearer access_token. Refresh with exchange_token (grant_type=refresh_token). Access tokens expire in 5 minutes; refresh tokens should be stored long-term for recurrence.

Base URLs are derived from NUPAY_ENV:

SandboxProduction
APIhttps://sandbox-api.spinpay.com.brhttps://api.spinpay.com.br
Authhttps://sandbox-authentication.spinpay.com.br/apihttps://authentication.spinpay.com.br/api

JWT client_assertion signing is the caller's responsibility — exchange_token expects an already-signed assertion with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Run

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

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/nupay/README.md，提交 d0a519a

工具

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

版本历史

1
  1. v0.2.2最新Sep 16, 2026

评分

已满足适用检查项的 50%

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

  • 近 30 天内可连通25 分

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

  • 已声明认证方式10 分

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

  • 已列出工具15 分

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

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