NovaPay MCP Server

MCP stdio сервер для NovaPay поверх офіційного SDK novapay. Підключіть його до будь-якого MCP-сумісного агента (Claude Desktop, Claude Code, власні агенти) — і агент зможе створювати платіжні посилання, опитувати статус оплат, керувати життєвим циклом сесій і генерувати ключі мерчанта.

📖 Documentation in English

Зміст · Вимоги · Підключення · Онбординг з нуля · Інструменти · Розробка · Ліцензія

Вимоги

• Node.js 20.3+

Підключення

Додайте у конфіг вашого MCP-клієнта:

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

PEM можна вставляти як з \n-екранами (як у прикладі), так і багаторядковим значенням — сервер розуміє обидва варіанти.

Змінні середовища

| Змінна | Обов'язкова | Опис | |---|---|---| | MERCHANT_PRIVATE_KEY | так | Приватний RSA-ключ мерчанта (PEM). Підписує всі запити до NovaPay | | MERCHANT_ID | так | Ідентифікатор мерчанта в NovaPay | | NOVAPAY_ENVIRONMENT | так | stage — тестове середовище NovaPay (api-qecom.novapay.ua), prod — продакшен (api-ecom.novapay.ua) | | NOVAPAY_PUBLIC_KEY | ні | Публічний ключ NovaPay (PEM). У stdio-режимі не використовується — postback-и сервер не приймає |

Без конфігурації сервер все одно стартує: доступним лишається generate_keys, а платіжні інструменти повертають помилку з переліком відсутніх змінних.

Онбординг з нуля

Немає ключів? Вони генеруються прямо з агента:

1. Підключіть сервер без env (або з частковим env) і попросіть агента викликати generate_keys.
2. Публічний ключ з відповіді зареєструйте в NovaPay (адмін-панель Acquiring3 або через підтримку).
3. Вміст файлу приватного ключа (шлях буде у відповіді, файл у ~/.novapay/, права 0600) вставте у MERCHANT_PRIVATE_KEY, додайте MERCHANT_ID і NOVAPAY_ENVIRONMENT.
4. Перезапустіть MCP-сервер — платіжні інструменти запрацюють.

Приватний ключ ніколи не повертається у відповіді інструмента — тільки шлях до файлу, тож ключ не осідає в контексті агента і логах.

Інструменти

Онбординг

• generate_keys — згенерувати RSA-пару 2048 для мерчанта. Працює без конфігурації.

Створення платежів (сесія може містити кілька платежів)

• create_acquiring_session — створити сесію Internet Acquiring → id сесії.
• add_acquiring_payment — додати платіж до сесії → платіжний URL для клієнта.
• create_checkout_session — створити сесію Checkout (оплата + доставка Нової Пошти) → id сесії.
• add_checkout_payment — додати платіж до checkout-сесії → платіжний URL.

Обидва add_*_payment вимагають явного use_hold: true — заблокувати кошти для пізнішого списання через complete_hold, false — списати одразу. Якщо користувач не сказав, як саме, — агент має спитати.

Життєвий цикл сесії (спільні для acquiring і checkout)

• get_session_status — статус сесії, суми, список операцій. Це єдиний спосіб побачити результат операцій нижче.
• complete_hold — списати захолджені кошти (можливо, частково).
• void_session — скасувати оплачену/захолджену сесію. На оплаченій сесії це рефанд реальних грошей.
• expire_session — інвалідувати неоплачену сесію (скасувати платіжне посилання).

create_*_session ──▶ add_*_payment ──▶ url
                          │
                   клієнт оплачує
                          ├─ use_hold: true ──▶ holded ──complete_hold──▶ paid
                          └─ use_hold: false ──────────────────────────▶ paid
                                                                          │
   неоплачена ──expire_session──▶ expired             void_session ◀──────┘
                                                          ▼
                                                        voided

Розробка

npm install
npm test        # tsc --noEmit + node:test
npm run build   # tsc → dist/

Smoke-тест на тестовому середовищі NovaPay можливий з опублікованими QE-ключами (мерчант 2) зі сторінки Автентифікація.

CI ганяє ті самі перевірки на Node 20, 22 і 24 для кожного push і pull request; тег v* публікує пакет в npm.

Ліцензія

MIT