# mcp-nupay

Connects AI assistants to the NuPay merchant checkout by Nubank. It handles Pix transactions, manages shopper refunds, and configures recurring billing flows.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/payments/nupay
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-nupay

## What it does

The server exposes 22 distinct tools directly tied to NuPay checkout endpoints. Assistants can initiate transactions, look up payment states via `pspReferenceId`, void pending requests, and issue partial or full refunds. It also covers merchant settlement reports and recipient registration for regulatory payment splits.

Two authentication modes exist. Standard actions need `NUPAY_MERCHANT_KEY` alongside `NUPAY_MERCHANT_TOKEN`. Reusable tokens and recurring checkouts rely on OAuth2 CIBA workflows with one-time passwords. Signing the JWT `client_assertion` must happen on your side before invoking `exchange_token`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NUPAY_MERCHANT_KEY`, `NUPAY_MERCHANT_TOKEN`, `NUPAY_CLIENT_ID`, `NUPAY_CLIENT_SECRET`, `NUPAY_ENV` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> --env NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> --env NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> --env NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> --env NUPAY_ENV=<NUPAY_ENV> --transport stdio nupay -- npx -y @codespar/mcp-nupay
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add nupay --env NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> --env NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> --env NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> --env NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> --env NUPAY_ENV=<NUPAY_ENV> -- npx -y @codespar/mcp-nupay
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "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>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nupay": {
            "type": "stdio",
            "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>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NUPAY_MERCHANT_KEY=<NUPAY_MERCHANT_KEY> -e NUPAY_MERCHANT_TOKEN=<NUPAY_MERCHANT_TOKEN> -e NUPAY_CLIENT_ID=<NUPAY_CLIENT_ID> -e NUPAY_CLIENT_SECRET=<NUPAY_CLIENT_SECRET> -e NUPAY_ENV=<NUPAY_ENV> nupay npx -y @codespar/mcp-nupay
```
Replace <…> with your own values

## When to use it
- create checkout charges via Pix and mobile wallet
- inspect payment progress using `pspReferenceId`
- issue full or partial customer refunds
- initiate recurring authorization flows with one-time passwords

## Example prompts
- Generate a NuPay payment for 120 BRL and retrieve its status
- Issue a partial refund for payment reference `pspReferenceId`
- Initiate buyer pre-authorization using `backchannel_start`

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md