NuPay

v0.2.0API Key

Nubank's merchant checkout rail — wallet-backed one-click, Pix, and recurrence, backed by Nubank's 100M+ BR customer distribution. Full OpenAPI verified; base platform is Spinpay.

22 tools5 env vars🇧🇷 Brazilstable on npm

Install

terminal

$ npm install @codespar/mcp-nupay

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "nupay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-nupay"
      ],
      "env": {
        "NUPAY_MERCHANT_KEY": "<your_nupay_merchant_key>",
        "NUPAY_MERCHANT_TOKEN": "<your_nupay_merchant_token>"
      }
    }
  }
}

After restart, your agent can call any of the 22 tools below — try create_payment first.

Environment variables · 5

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

NUPAY_MERCHANT_KEY

required

NuPay X-Merchant-Key issued to your merchant

NUPAY_MERCHANT_TOKEN

requiredsecret

NuPay X-Merchant-Token issued to your merchant

NUPAY_CLIENT_ID

optional

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

NUPAY_CLIENT_SECRET

optionalsecret

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

NUPAY_ENV

optional

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

Available tools · 22

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEcreate_payment

Create a NuPay checkout payment. Returns pspReferenceId + the redirect/QR payload the shopper needs to complete the charge (NuPay wallet push or Pix). Use merchant-key auth.

WRITEget_payment

Retrieve full payment details (amount, shopper, items, current status, timestamps) by pspReferenceId. Use this for richer detail than get_payment_status.

WRITEget_payment_status

Retrieve a payment's status by pspReferenceId.

WRITElist_payments_by_date

List payments created within a date range. Supports cursor pagination via limit + offset. Useful for reconciliation and reporting.

DELETEcancel_payment

Cancel a payment that has not yet been captured/settled.

DELETEcreate_refund

Refund a settled payment (full or partial). Idempotent via transactionRefundId.

DELETEget_refund

Retrieve refund status by pspReferenceId + refundId.

READlist_refunds

List all refunds issued against a given payment.

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.