payware

payware MCP Server

Official MCP (Model Context Protocol) server for payware payment API integration. This server enables AI assistants to interact with payware APIs, automating integration workflows for all partner types.

Releases are published to npm as @payware/mcp-server and to the official MCP Registry as io.github.payware/mcp-server. MIT licensed, see LICENSE.

Who Is This For?

• Merchants - Accept payments, manage products, generate transaction reports
• ISVs (Independent Software Vendors) - Build multi-merchant platforms with OAuth2 token management
• Payment Institutions - Process A2A transfers, handle Payment Choice Architecture with multiple payment methods

What's New in 2.2.2

• The deferred Fee Leg goes after CONFIRMED - for every transfer type the Fee Leg is executed only after payware has accepted CONFIRMED; during a DEFERRED transfer the institution keeps the Fee Amount reserved on the payer's account and releases it if the Merchant Leg fails. feeLegOutcome is optional and only NOT_EXECUTED is accepted: the finalize tool refuses RETURNED before sending
• A merchant that can no longer accept payments - the institution tools describe ERR_PAYEE_UNAVAILABLE (409): payware refuses EXECUTING for a merchant that is switched off, nothing is locked and no money may move

What's New in 2.2.1

• Partial product and schedule updates - update_product and update_schedule send only the fields you give, and payware keeps every stored value the request leaves out. 2.2.0 read the product first and sent it whole, which payware refuses once the product's start date has passed
• ISV product images - payware_products_get_product_image works for an ISV acting for a merchant, on the merchant's plan and for products in the shops the merchant assigned to the ISV
• ISV reports, two ways - with a merchant's token an ISV runs that merchant's reports, limited to the shops the merchant assigned to it; without one, its own reports on everything it handled. Each request is found only in the context it was run in

What's New in 2.2.0

• Execution lock - A payment institution finalizes with EXECUTING immediately before money moves, then CONFIRMED once the Merchant Leg has completed, or FAILED; transferType and feeLegOutcome are new
• Deferred Merchant Leg - Merchants, and ISVs for them, can allow a credit transfer that settles later with deferredAllowed
• Code examples - payware_generate_code_example writes complete, signed programs for real routes only, including the institution finalize flow

Features

🔐 Authentication Tools

• RSA Key Generation: Generate secure 2048-bit RSA key pairs
• JWT Token Creation: Create properly formatted JWT tokens
• Sandbox Setup: Configure sandbox authentication

💳 Transaction Tools

• Create Transaction: Support PLAIN, QR, and BARCODE transactions
• Process Transaction: Process transactions with Payment Choice Architecture support
• Transaction Status: Check transaction status by ID
• Transaction History: Get finalized transaction details
• Callback Simulation: Test callback scenarios for merchants and payment institutions

📍 Point of Interaction (POI) Tools

• Set Price: Configure POI with amount, currency, and payment details
• Cancel Price: Clear active price from POI
• Get POI: Retrieve POI details and current state
• Get Status: Check POI transaction status
• Get QR Code: Generate QR code for POI payments
• List POIs: List all POIs for a merchant

📣 Campaign, Placement and Airing Tools

For merchants, and for ISVs acting for them. Changes need the merchant's PRM plan; reading works on every plan.

• Placements: Distribute a product through posters, TV spots, packaging, links or tags, each with its own pl ID, so every payment it starts is attributed to it. Includes the QR code, barcode and short link of each placement
• Campaigns: Group placements, across products, and read their combined results
• Airing Rules: Schedule when a placement is on air, with recurrences, time windows and time zones, and replace a whole schedule in one call
• Airing Calendar: Every airing across all products in a time range
• Results: Offers shown, payments started and confirmed, and confirmed amounts per placement or campaign

📋 Logs Tools (Premium)

• Query Logs: Search and filter application logs by level, logger, message content, and date range
• Log Status: Check log availability and storage information
• Download Logs: Get compressed archive of logs for offline analysis

🛠️ Utility Tools

• Code Examples: A complete program for one API call, or the JWT helper, in Python, Node.js, PHP, Java, C# or curl, signed as payware requires and calling the real route
• Integration Overview: Base URLs, request signing and every operation the code examples cover, per partner type
• Request Formatting: Format and validate API requests

Quick Start

1. Installation

From npm (recommended):

npm install -g @payware/mcp-server

From source:

git clone https://github.com/payware/mcp-server.git

cd mcp-server npm install

2. Environment Configuration

Copy the example environment file and configure your credentials:

cp .env.example .env

Edit .env file:

# Partner ID from payware dashboard

PAYWARE_PARTNER_ID=your_partner_id_here

Path to private key file (relative to project root)

PAYWARE_SANDBOX_PRIVATE_KEY_PATH=keys/sandbox-your-private-key.pem PAYWARE_PRODUCTION_PRIVATE_KEY_PATH=keys/production-your-private-key.pem

Optional: Sandbox base URL (defaults to https://sandbox.payware.eu/api)

PAYWARE_SANDBOX_URL=https://sandbox.payware.eu/api

⚠️ Security Note: Never commit the .env file to version control. It contains sensitive credentials.

Choosing toolsets

Every tool definition goes into the assistant's context on every turn, and a merchant has over 70 of them. To offer only the groups you use, set PAYWARE_MCP_TOOLSETS to a comma-separated list:

PAYWARE_MCP_TOOLSETS=products,placements

Toolsets: auth, transactions, products, placements, data, logs, poi, shops, onboarding, utils. Unset, or all, loads every tool. An unknown name is ignored with a warning in the server log. A tool outside the chosen toolsets is neither listed nor callable; this narrows what the assistant is offered and does not change what your partner account may do. An ISV that obtains OAuth2 tokens through this server includes auth.

3. Start the MCP Server

npm start

4. Basic Integration Flow

1. Generate RSA Keys

   Tool: payware_authentication_generate_rsa_keys

1. Create JWT Token

   Tool: payware_authentication_create_jwt_token

Parameters:

• partnerId: (from PAYWARE_PARTNER_ID)
• privateKey: (from environment-specific key path)

1. Setup Sandbox

   Tool: payware_authentication_setup_sandbox_auth

Parameters:

• partnerId: (from PAYWARE_PARTNER_ID)

1. Create Transaction

   Tool: payware_operations_create_transaction

Parameters:

• partnerId: (from PAYWARE_PARTNER_ID)
• privateKey: (from environment-specific key path)
• amount: 10.00
• currency: EUR
• reasonL1: "Payment description"
• type: PLAIN

1. Check Status

   Tool: payware_operations_get_transaction_status

Parameters:

• partnerId: (from PAYWARE_PARTNER_ID)
• privateKey: (from environment-specific key path)
• transactionId: TRANSACTION_ID

API Request Structure

The payware MCP server transforms flat parameter inputs into the proper nested JSON structure required by the payware API:

Create Transaction Request Structure

{

// ROOT LEVEL - Transaction metadata "shop": "SHOP001", // Optional: Shop code "account": "GB29NWBK60161331926810", // Optional: Account identifier "friendlyName": "Your Shop Name", // Optional: Account holder name "callbackUrl": "https://callback.url", // Optional: HTTPS callback URL "passbackParams": "{\"orderId\":\"12345\"}", // Optional: Callback parameters

// TRANSACTION DATA - Required transaction information "trData": { "amount": "25.50", // String/Number: Amount (can be "0.00" for flexible amounts) "currency": "EUR", // REQUIRED: ISO 3-character currency code "reasonL1": "Payment for services", // REQUIRED: Transaction description (max 100 chars) "reasonL2": "Order #12345" // Optional: Additional description (max 100 chars) },

// TRANSACTION OPTIONS - Transaction behavior settings "trOptions": { "type": "QR", // PLAIN, QR, or BARCODE (default: PLAIN) "timeToLive": 300 // Seconds: 60-600 (default: 120) },

// QR OPTIONS - Only included when type=QR "qrOptions": { "qrFormat": "PNG", // PNG, JPG, SVG (default: SVG) "qrBorder": 4, // Border modules: 1-10 (default: 4) "qrErrorCorrection": "QUARTILE", // LOW, MEDIUM, QUARTILE, HIGH (default: QUARTILE) "qrScale": 16, // Pixel size: 1-100 (default: 16, irrelevant for SVG) "qrVersion": 10 // QR version: 1-40 (default: 3) },

// BARCODE OPTIONS - Only included when type=BARCODE "barOptions": { "barFormat": "SVG", // PNG, SVG, JPG (default: SVG) "barModuleWidth": 2, // Module width: 1-10 (default: 2) "barBarHeight": 100, // Height: 15-1000 (default: 100) "barFontSize": 12, // Font size: 0-24 (default: 12) "barHumanReadableLocation": "NONE" // NONE, BOTTOM, TOP (default: NONE) } }

Parameter Mapping

When using MCP tools, parameters are automatically mapped to the correct API structure:

Available Tools

Code Generation & Documentation

payware_generate_code_example

A complete program for one payware API call, in Python, Node.js, PHP, Java, C# or curl

Each program signs its request with an RS256 JWT (contentSha256 for a body; on behalf of a merchant for an ISV, except the OAuth2 endpoints) and calls a route the server has. The operations, by partner type:

• Transactions (all): create_transaction, get_transaction_status, process_transaction, cancel_transaction, get_transaction_history
• Institution finalize (payment_institution): finalize_transaction, the whole flow - process, then EXECUTING immediately before money moves, then CONFIRMED once the Merchant Leg has completed or FAILED, on PATCH /api/transactions/{transactionId}
• Products and audio (merchant, isv): create_product, get