io.github.codespar/mcp-nupay (MCP Server)

MCP server for NuPay (Nubank merchant checkout). It supports NuPay’s wallet-backed checkout for Brazil, enabling agents to create payments that shoppers confirm in the Nubank app (push + biometric) or via Pix. The server also covers pre-authorized recurrence flows using CIBA/OTP for repeat buyers.

🛠️ Key Features

NuPay integration for Nubank merchant checkout rail
Payment creation for agent-driven flows
Shopper confirmation via Nubank app or Pix
Pre-authorized recurring payments using CIBA/OTP

🚀 Use Cases

Agent-generated checkout for Nubank merchants
One-click style repeat buyer payments through pre-authorized flows
Pix-based shopper completion of NuPay payments

⚡ Developer Benefits

Model Context Protocol (MCP) tools for checkout automation
Works with NuPay’s payment lifecycle: create and retrieve payments
Focus on Brazil and open-finance/fintech payment use in agents

⚠️ Limitations

Tool list and full capabilities are only partially shown in the provided source excerpt (22 tools are mentioned, but details are truncated).

@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

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.

Environment

bash

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.

Install

Configuration

Environment variables

NUPAY_MERCHANT_KEYrequired

NuPay X-Merchant-Key issued to your merchant

NUPAY_MERCHANT_TOKENrequiredsecret

NuPay X-Merchant-Token issued to your merchant

NUPAY_CLIENT_ID

OAuth2/CIBA client_id for pre-authorized (recurrence) flows. Optional unless using backchannel_start / backchannel_complete.

NUPAY_CLIENT_SECRETsecret

OAuth2/CIBA client_secret for pre-authorized flows. Optional unless using backchannel_* tools.

NUPAY_ENV

sandbox | production. Defaults to sandbox. Drives both checkout API and auth base URLs.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-nupay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-nupay@0.2.2"
      ],
      "env": {
        "NUPAY_MERCHANT_KEY": "<YOUR_NUPAY_MERCHANT_KEY>",
        "NUPAY_MERCHANT_TOKEN": "<YOUR_NUPAY_MERCHANT_TOKEN>",
        "NUPAY_CLIENT_ID": "<YOUR_NUPAY_CLIENT_ID>",
        "NUPAY_CLIENT_SECRET": "<YOUR_NUPAY_CLIENT_SECRET>",
        "NUPAY_ENV": "<YOUR_NUPAY_ENV>"
      }
    }
  }
}

io.github.codespar/mcp-nupay