# NovaPay MCP Server

[![CI](https://github.com/NovaPay/novapay-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/NovaPay/novapay-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/novapay-mcp.svg)](https://www.npmjs.com/package/novapay-mcp)
[![install size](https://packagephobia.com/badge?p=novapay-mcp)](https://packagephobia.com/result?p=novapay-mcp)
[![license](https://img.shields.io/npm/l/novapay-mcp.svg)](LICENSE)

MCP stdio server for [NovaPay](https://novapay.ua) on top of the official [`novapay`](https://www.npmjs.com/package/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.

📖 [Документація українською](README.uk.md)

**Contents** · [Requirements](#requirements) · [Setup](#setup) · [Onboarding from scratch](#onboarding-from-scratch) · [Tools](#tools) · [Development](#development) · [License](#license)

## Requirements

- **Node.js 20.3+**

## Setup

Add to your MCP client config:

```json
{
  "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

```bash
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](https://novapay.readme.io/reference/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](LICENSE)