Mcp Nupay

io.github.codesparPublished by GitHub account codesparv0.2.2Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

MCP server for NuPay, Nubank's Brazilian merchant checkout, letting an assistant create, inspect, cancel and refund payments and manage payouts.

What you can do
  • Create, retrieve, list and cancel NuPay checkout payments, and check payment status by reference.
  • Issue full or partial refunds and look up refund status and refund lists.
  • Register, update, delete and list final beneficiaries (recipients) for split payments.
  • List settlement reports and inspect individual payout batches and their transactions.
  • Query installment and payment conditions for an amount, optionally with a shopper CPF.
  • Run pre-authorized and recurrence flows: start and complete CIBA/OTP authorization, resend OTP, create pre-authorized payments, and exchange or revoke OAuth tokens.
When to use it
Useful when an assistant needs to operate a NuPay merchant account for Brazilian customers: taking checkout payments, handling refunds, tracking settlements, or building repeat-buyer one-click and recurrence flows.
Requirements
Runs locally over stdio via the npm package (Node.js), or over HTTP when MCP_HTTP and MCP_PORT are set. Requires NUPAY_MERCHANT_KEY and NUPAY_MERCHANT_TOKEN; NUPAY_CLIENT_ID and NUPAY_CLIENT_SECRET are needed only for the backchannel pre-authorization tools. NUPAY_ENV selects sandbox (default) or production and determines the API and auth base URLs. Network access to the NuPay/Spinpay endpoints is required.
Before you install
This server moves real money: it creates payments, issues refunds, cancels payments, deletes recipients and revokes tokens. NUPAY_MERCHANT_TOKEN and NUPAY_CLIENT_SECRET are merchant secrets and must be kept private. NUPAY_ENV defaults to sandbox, but switching it to production points the same tools at live endpoints. Pre-authorized flows involve shopper OTPs and long-lived refresh tokens that the caller must store and sign client assertions for. Payment and shopper data, including CPF, is sent…

Installation

In SourceWeft

  1. Open Mcp Nupay in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: packages/payments/nupay/README.md at commit d0a519a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts