Skip to main content
Glama
novapay-mcp

novapay-mcp

Official
by NovaPay

NovaPay MCP Server

CI npm install size license

MCP stdio server for NovaPay on top of the official novapay SDK. Connect it to any MCP-compatible agent (Claude Desktop, Claude Code, custom agents) β€” and the agent can create payment links, poll payment status, drive the session lifecycle and generate merchant keys.

πŸ“– ДокумСнтація ΡƒΠΊΡ€Π°Ρ—Π½ΡΡŒΠΊΠΎΡŽ

Contents Β· Requirements Β· Setup Β· Onboarding from scratch Β· Tools Β· Development Β· License

Requirements

  • Node.js 20.3+

Related MCP server: alipay-mcp-server

Setup

Add to your MCP client config:

{
  "mcpServers": {
    "novapay": {
      "command": "npx",
      "args": ["-y", "novapay-mcp"],
      "env": {
        "MERCHANT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----",
        "MERCHANT_ID": "<your merchant id>",
        "NOVAPAY_ENVIRONMENT": "stage"
      }
    }
  }
}

The PEM can be pasted either with \n escapes (as in the example) or as a multi-line value β€” the server understands both.

Environment variables

Variable

Required

Description

MERCHANT_PRIVATE_KEY

yes

Merchant's private RSA key (PEM). Signs every request to NovaPay

MERCHANT_ID

yes

Merchant identifier in NovaPay

NOVAPAY_ENVIRONMENT

yes

stage β€” NovaPay test environment (api-qecom.novapay.ua), prod β€” production (api-ecom.novapay.ua)

NOVAPAY_PUBLIC_KEY

no

NovaPay public key (PEM). Unused in stdio mode β€” the server does not receive postbacks

The server starts without configuration too: generate_keys stays available, and the payment tools return an error listing the missing variables.

Onboarding from scratch

No keys yet? Generate them straight from the agent:

  1. Connect the server without env (or with a partial env) and ask the agent to call generate_keys.

  2. Register the public key from the response with NovaPay (Acquiring3 admin panel or via support).

  3. Paste the contents of the private key file (the path is in the response, the file lives in ~/.novapay/ with 0600 permissions) into MERCHANT_PRIVATE_KEY, add MERCHANT_ID and NOVAPAY_ENVIRONMENT.

  4. Restart the MCP server β€” the payment tools go live.

The private key is never returned in a tool response β€” only the file path, so the key never lands in the agent's context or logs.

Tools

Onboarding

  • generate_keys β€” generate a 2048-bit RSA pair for the merchant. Works without configuration.

Creating payments (a session can hold several payments)

  • create_acquiring_session β€” create an Internet Acquiring session β†’ session id.

  • add_acquiring_payment β€” add a payment to the session β†’ payment URL for the customer.

  • create_checkout_session β€” create a Checkout session (payment + Nova Poshta delivery) β†’ session id.

  • add_checkout_payment β€” add a payment to a checkout session β†’ payment URL.

Both add_*_payment require an explicit use_hold: true β€” hold the funds for a later capture via complete_hold, false β€” charge immediately. If the user did not say which, the agent should ask.

Session lifecycle (shared by acquiring and checkout)

  • get_session_status β€” session status, amounts, list of operations. The only way to see the result of the operations below.

  • complete_hold β€” capture the held funds (possibly partially).

  • void_session β€” cancel a paid/held session. On a paid session this refunds real money.

  • expire_session β€” invalidate an unpaid session (cancel the payment link).

create_*_session ──▢ add_*_payment ──▢ url
                          β”‚
                    customer pays
                          β”œβ”€ use_hold: true ──▢ holded ──complete_hold──▢ paid
                          └─ use_hold: false ──────────────────────────▢ paid
                                                                          β”‚
       unpaid ──expire_session──▢ expired             void_session β—€β”€β”€β”€β”€β”€β”€β”˜
                                                          β–Ό
                                                        voided

Development

npm install
npm test        # tsc --noEmit + node:test
npm run build   # tsc β†’ dist/

A smoke test against the NovaPay stage environment is possible with the published QE keys (merchant 2) from the Authentication page.

CI runs the same checks on Node 20, 22 and 24 for every push and pull request; pushing a v* tag publishes the package to npm.

License

MIT

Available Tools

9 tools
add_acquiring_paymentAdd acquiring payment (get payment URL)A

Add a payment to an existing acquiring session. Returns the payment URL to send to the customer, plus the session and transaction ids. Call again with the same session_id to add more payments.

Inputs: amount (required), use_hold (required), session_id (required), delivery, +3 more.

add_checkout_paymentAdd checkout payment (get payment URL)A

Add a payment to an existing checkout session. Returns the checkout URL to send to the customer plus the session id (the transaction id appears later in get_session_status).

Inputs: amount (required), use_hold (required), session_id (required), delivery, +3 more.

complete_holdComplete hold (capture funds)A

Capture funds previously held with use_hold=true, moving the session from holded to paid. Optionally capture a smaller amount than was held. NovaPay returns no body for this call β€” check the result with get_session_status.

Inputs: session_id (required), amount.

create_acquiring_sessionCreate acquiring sessionA

Create a NovaPay Internet Acquiring payment session. Returns the session id. To get a payment URL for the customer, follow up with add_acquiring_payment. A session can hold multiple payments.

Inputs: client_phone (required), fail_url, metadata, success_url, +6 more.

create_checkout_sessionCreate checkout sessionA

Create a NovaPay Checkout session (payment + Nova Poshta delivery collection). Returns the session id. To get a payment URL for the customer, follow up with add_checkout_payment.

Inputs: callback_url (required), delivery, fail_url, metadata, +3 more.

expire_sessionExpire unpaid session (cancel payment link)A

Invalidate an UNPAID session so its payment URL can no longer be paid. Use this to cancel a payment link that was created by mistake or is no longer needed. NovaPay returns no body β€” check the result with get_session_status.

Inputs: session_id (required).

generate_keysGenerate merchant RSA keysA

Generate an RSA 2048 keypair for NovaPay merchant onboarding. Returns the PUBLIC key (register it with NovaPay via the Acquiring3 admin panel or NovaPay support) and the file path of the PRIVATE key. The private key itself is never returned. Works without any configuration β€” this is the first onboarding step.

Inputs: no named parameters.

get_session_statusGet session statusA

Get the current status of a payment session (acquiring or checkout): lifecycle status (created/holded/paid/voided/expired/...), transaction status, amounts (decimal strings) and the list of payment operations. Use this to poll for payment results and to verify the outcome of complete_hold / void_session / expire_session.

Inputs: session_id (required).

void_sessionVoid session (refund)A

Cancel a PAID or HELD session: releases a hold or REFUNDS an already charged payment β€” real money moves back to the customer. Confirm with the user before calling this on a paid session. For unpaid sessions use expire_session instead. NovaPay returns no body β€” check the result with get_session_status.

Inputs: session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource/action: key generation, two session creation flows, two payment addition flows, status retrieval, and three lifecycle operations. The distinction between acquiring and checkout sessions is clear, and void/expire/complete_hold have explicit use-case boundaries.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (generate_keys, create_acquiring_session, add_checkout_payment, etc.). The verbs and objects are uniformly structured, with no mixed casing or naming style deviations.

    Tool Count5/5

    With 9 tools, the set is well-scoped for a payment processing server. Each tool serves a distinct step in the payment lifecycleβ€”onboarding, session creation, payment addition, status polling, and post-payment actionsβ€”without redundancy or bloat.

    Completeness5/5

    The tool set covers the full payment session lifecycle: key generation, session creation for both acquiring and checkout, payment addition, status tracking, and resolution via hold completion, void, or expiration. There are no obvious dead ends or missing operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for AgentPay β€” the payment gateway for autonomous AI agents. Fund a wallet once, give your agent the key, and it discovers, provisions, and pays for tool APIs on its own. One key, every tool.
      112 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that lets AI agents interact with the Adaptis (MEG) payment gateway, enabling payment link creation, transaction queries, refunds, and integration helpers like generating signed forms and verifying callbacks.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server to connect AI assistants to the AdvinPay payment API, enabling PIX charges, transaction queries, and documentation search.
      MIT