novapay-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@novapay-mcp Create a payment link for 1000 UAH, hold the funds"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NovaPay MCP Server
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 |
| yes | Merchant's private RSA key (PEM). Signs every request to NovaPay |
| yes | Merchant identifier in NovaPay |
| yes |
|
| 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:
Connect the server without env (or with a partial env) and ask the agent to call
generate_keys.Register the public key from the response with NovaPay (Acquiring3 admin panel or via support).
Paste the contents of the private key file (the path is in the response, the file lives in
~/.novapay/with0600permissions) intoMERCHANT_PRIVATE_KEY, addMERCHANT_IDandNOVAPAY_ENVIRONMENT.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 β sessionid.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) β sessionid.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 ββββββββ
βΌ
voidedDevelopment
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
Available Tools
9 toolsadd_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
MCP server for Modern Treasury β payment orders, transactions, counterparties and ledgers.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP 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 npm1MIT
- AlicenseAqualityBmaintenanceAn MCP server that exposes Alipay AI Pay capabilities to AI agents, enabling skill discovery, payment integration guides, and merchant onboarding workflows via Alipay's payment APIs.4114 npmMIT
- FlicenseNot gradedqualityBmaintenanceA 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.-

AdvinPay MCPofficial
AlicenseNot gradedqualityDmaintenanceMCP server to connect AI assistants to the AdvinPay payment API, enabling PIX charges, transaction queries, and documentation search.MIT