io.github.codespar/mcp-nupay

io.github.codespar/mcp-nupay · 273 stars · TypeScript · MIT

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

Install

The repo has no one-line install. Follow its README.

Published as

npm@codespar/mcp-nupaystdio

From the server's entry in the official MCP Registry.

Open the repo

Configuration

Name	Set as	What it is
`NUPAY_MERCHANT_KEY`Required	Env var	NuPay X-Merchant-Key issued to your merchant
`NUPAY_MERCHANT_TOKEN`Required · Secret	Env var	NuPay X-Merchant-Token issued to your merchant
`NUPAY_CLIENT_ID`Optional	Env var	OAuth2/CIBA client_id for pre-authorized (recurrence) flows. Optional unless using backchannel_start / backchannel_complete.
`NUPAY_CLIENT_SECRET`Optional · Secret	Env var	OAuth2/CIBA client_secret for pre-authorized flows. Optional unless using backchannel_* tools.
`NUPAY_ENV`Optional	Env var	sandbox \| production. Defaults to sandbox. Drives both checkout API and auth base URLs.

Files

packages/payments/nupay/README.md

@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)

Tool	Purpose
`create_payment`	Create a NuPay checkout payment.
`get_payment`	Retrieve full payment details (amount, shopper, items, current status, timestamps) by pspReferenceId.
`get_payment_status`	Retrieve a payment's status by pspReferenceId.
`list_payments_by_date`	List payments created within a date range.
`cancel_payment`	Cancel a payment that has not yet been captured/settled.
`create_refund`	Refund a settled payment (full or partial).
`get_refund`	Retrieve refund status by pspReferenceId + refundId.
`list_refunds`	List all refunds issued against a given payment.
`create_recipient`	Register a final beneficiary (required for regulatory split payments).
`get_recipient`	Retrieve a registered recipient by referenceId.
`update_recipient`	Update a registered final beneficiary (name, document, country, type).
`delete_recipient`	Remove a registered recipient.
`list_recipients`	List registered recipients (final beneficiaries) for the merchant.
`list_settlements`	List settlement reports (payouts to the merchant bank account) within a date range.
`get_settlement`	Retrieve a single settlement (payout batch) including the list of underlying transactions.
`query_payment_conditions`	Query available installment/payment conditions for a given amount and (optionally) shopper CPF.
`create_preauth_payment`	Create a NuPay payment using a pre-authorized Bearer access_token (pre-auth / recurrence flow).
`backchannel_start`	Start a CIBA / OTP pre-authorization for a shopper.
`backchannel_complete`	Complete a CIBA/OTP flow by submitting the OTP the shopper received.
`backchannel_resend_otp`	Resend the OTP to the shopper for an in-flight authorization ticket.
`exchange_token`	Exchange an authorization_code or refresh_token at POST /v1/token.
`revoke_token`	Revoke an issued access_token or refresh_token at POST /v1/token/revoke.

Install

npm install @codespar/mcp-nupay

Environment

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

Authentication

Two flows:

Standard merchant API (payments, refunds, recipients, payment-conditions) uses X-Merchant-Key + X-Merchant-Token headers. No token exchange.
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:

	Sandbox	Production
API	`https://sandbox-api.spinpay.com.br`	`https://api.spinpay.com.br`
Auth	`https://sandbox-authentication.spinpay.com.br/api`	`https://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

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

# HTTP
MCP_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

Facts

Kind: MCP server
Repo: codespar/mcp-dev-latam
Group: Uncategorized
Stars: 273
License: MIT
Language: TypeScript
Last push: 2026-09-27
Forks: 50
MCP Registry: io.github.codespar/mcp-nupay
Homepage: codespar.dev/servers
Topics: agentic-commerce, ai-agents, brazil, claude, fintech, latin-america, llm-tools, mcp, model-context-protocol, nfe, open-finance, payments, pix

io.github.codespar/mcp-nupay

Install

Published as

Configuration

Files

@codespar/mcp-nupay

Tools (22)

Install

Environment

Authentication

Run

Enterprise

License

Facts

More on this shelf