Ermöglicht es KI-Assistenten, mit Payware-APIs zu interagieren, um A2A-Zahlungen zu automatisieren, Produkte zu verwalten und Transaktions-Workflows für Merchants und ISVs abzuwickeln.
Auch bekannt als payware/mcp-server, mcp-server, @payware/mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- 2.3.0
- Letzter Commit
- 15. Nov. 2026
- Lizenz
- MIT
Was ist payware MCP?
Ermöglicht es KI-Assistenten, mit Payware-APIs zu interagieren, um A2A-Zahlungen zu automatisieren, Produkte zu verwalten und Transaktions-Workflows für Merchants und ISVs abzuwickeln.
Zusammenfassung generiert aus dem README des Projekts
Über payware MCP server
Der payware MCP server bietet eine Schnittstelle für KI-Assistenten, um Zahlungs-Workflows zu verwalten und mit Payware-APIs zu interagieren. Er wurde für Merchants, Independent Software Vendors (ISVs) und Zahlungsinstitute entwickelt. Nutzer können Aufgaben wie die Abwicklung von A2A-Transfers, die Verwaltung von Produktkatalogen und die Handhabung von Transaktions-Lebenszyklen automatisieren. Der Server unterstützt verschiedene Transaktionstypen wie PLAIN, QR und BARCODE und ermöglicht fortgeschrittene Konfigurationen wie deferred merchant legs und payment choice architecture.
Um diesen Server zu nutzen, müssen Entwickler Umgebungsvariablen konfigurieren, einschließlich einer Partner ID und Pfaden zu RSA-Private-Keys für Sandbox- oder Production-Umgebungen. Der Server kann via npm als @payware/mcp-server installiert werden. Um die Komplexität des Kontexts des Assistenten zu steuern, können Nutzer die verfügbaren Tools einschränken, indem sie die Variable PAYWARE_MCP_TOOLSETS auf spezifische Gruppen wie products, transactions oder placements setzen. Dieses Setup ermöglicht es dem Assistenten, sichere Operationen wie die Erstellung von JWT-Tokens und die RSA-Key-Generierung durchzuführen und dabei strenge Authentifizierungsstandards einzuhalten.
Was du damit machen kannst
- 1Verwaltung von Merchant-ProduktkatalogenEin Entwickler kann eine KI anweisen, spezifische Felder eines Produkts zu aktualisieren, ohne den gesamten gespeicherten Datensatz zu überschreiben.
- 2Generierung von produktionsbereitem IntegrationscodeEine KI kann ein vollständiges, signiertes Programm in mehreren Sprachen schreiben, um eine spezifische API-Route zu demonstrieren.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du payware MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenpayware MCP in Claude Code installieren
$ claude mcp add --env 'PAYWARE_OAUTH_CLIENT_SECRET=<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>' mcp-server -- npx -y @payware/mcp-serverpayware MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@payware/mcp-server"
],
"env": {
"PAYWARE_OAUTH_CLIENT_SECRET": "<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"
}
}
}
}payware MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@payware/mcp-server"
],
"env": {
"PAYWARE_OAUTH_CLIENT_SECRET": "<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"
}
}
}
}payware MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@payware/mcp-server"],"env":{"PAYWARE_OAUTH_CLIENT_SECRET":"<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"}}'payware MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@payware/mcp-server"
],
"env": {
"PAYWARE_OAUTH_CLIENT_SECRET": "<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"
}
}
}
}payware MCP in Codex installieren
$ codex mcp add mcp-server --env 'PAYWARE_OAUTH_CLIENT_SECRET=<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>' -- npx -y @payware/mcp-serverpayware MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@payware/mcp-server"] [mcp_servers.mcp-server.env] PAYWARE_OAUTH_CLIENT_SECRET = "<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"
payware MCP in Gemini CLI installieren
$ gemini mcp add -s user -e 'PAYWARE_OAUTH_CLIENT_SECRET=<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>' mcp-server npx -- -y @payware/mcp-serverpayware MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@payware/mcp-server"
],
"env": {
"PAYWARE_OAUTH_CLIENT_SECRET": "<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>"
}
}
}
}Konfiguration
PAYWARE_OAUTH_CLIENT_SECRETSecretOAuth2 client secret (ISV partners only)
PAYWARE_LINKS_BASE_URLPayer role only: the base URL of the public link host, e.g. http://localhost:8080 for a local payware server. Defaults to https://go-sandbox.payware.eu (sandbox) or https://go.payware.eu (production)
PAYWARE_MCP_TOOLSETSComma-separated toolsets to load, e.g. products,placements. Unset loads every tool. Toolsets: auth, transactions, products, placements, data, logs, poi, shops, onboarding, utils, payer
PAYWARE_OAUTH_CLIENT_IDOAuth2 client ID (ISV partners only)
PAYWARE_PARTNER_IDPartner ID from the payware dashboard (not needed for the payer role)
PAYWARE_PARTNER_TYPEPartner role: merchant, isv, payment_institution or payer (a buying agent, no keys needed)
PAYWARE_PRODUCTION_PRIVATE_KEY_PATHPath to the RSA private key for production
PAYWARE_SANDBOX_PRIVATE_KEY_PATHPath to the RSA private key for the sandbox (not needed for the payer role)
PAYWARE_SANDBOX_URL
| Name | Beschreibung | Typ |
|---|---|---|
| PAYWARE_OAUTH_CLIENT_SECRET | OAuth2 client secret (ISV partners only) | Secret |
| PAYWARE_LINKS_BASE_URL | Payer role only: the base URL of the public link host, e.g. http://localhost:8080 for a local payware server. Defaults to https://go-sandbox.payware.eu (sandbox) or https://go.payware.eu (production) | |
| PAYWARE_MCP_TOOLSETS | Comma-separated toolsets to load, e.g. products,placements. Unset loads every tool. Toolsets: auth, transactions, products, placements, data, logs, poi, shops, onboarding, utils, payer | |
| PAYWARE_OAUTH_CLIENT_ID | OAuth2 client ID (ISV partners only) | |
| PAYWARE_PARTNER_ID | Partner ID from the payware dashboard (not needed for the payer role) | |
| PAYWARE_PARTNER_TYPE | Partner role: merchant, isv, payment_institution or payer (a buying agent, no keys needed) | |
| PAYWARE_PRODUCTION_PRIVATE_KEY_PATH | Path to the RSA private key for production | |
| PAYWARE_SANDBOX_PRIVATE_KEY_PATH | Path to the RSA private key for the sandbox (not needed for the payer role) | |
| PAYWARE_SANDBOX_URL | — |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarpayware/mcp-server is public and reachablegithub.com/payware/mcp-server ↗Bestanden
- Paket nennt dieses Repository als Quelle@payware/mcp-server names payware/mcp-server as sourcenpmjs.com/package/@payware/mcp-server ↗Bestanden
- Build-Provenienz (Sigstore-Attestierung)No build attestation published for this releaseNicht geprüft
- Open Source Lizenz (OSI)MITspdx.org/licenses/MIT.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-11-13github.com/payware/mcp-server ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from @payware/mcp-serverBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeitenthe package checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenpayware 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.1
- Partial product and schedule updates -
update_productandupdate_schedulesend 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_imageworks 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
EXECUTINGimmediately before money moves, thenCONFIRMEDonce the Merchant Leg has completed, orFAILED;transferTypeandfeeLegOutcomeare new - Deferred Merchant Leg - Merchants, and ISVs for them, can allow a credit transfer that settles later with
deferredAllowed - Code examples -
payware_generate_code_examplewrites 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
plID, 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
-
Generate RSA Keys
Tool: payware_authentication_generate_rsa_keys -
Create JWT Token
Tool: payware_authentication_create_jwt_token Parameters: - partnerId: (from PAYWARE_PARTNER_ID) - privateKey: (from environment-specific key path) -
Setup Sandbox
Tool: payware_authentication_setup_sandbox_auth Parameters: - partnerId: (from PAYWARE_PARTNER_ID) -
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 -
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:
| MCP Tool Parameter | API Location | Description |
|---|---|---|
partnerId, privateKey |
Authentication | Used for JWT signing, not sent in request |
account, friendlyName, shop, callbackUrl, passbackParams |
Root Level | Transaction metadata |
amount, currency, reasonL1, reasonL2 |
trData object |
Core transaction data |
type, timeToLive, deferredAllowed |
trOptions object |
Transaction behavior (deferredAllowed: the merchant's opt-in to a deferred Merchant Leg, sent only when true) |
qrFormat, qrBorder, etc. |
qrOptions object |
QR code settings (when type=QR) |
barFormat, barModuleWidth, etc. |
barOptions object |
Barcode settings (when type=BARCODE) |
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
EXECUTINGimmediately before money moves, thenCONFIRMEDonce the Merchant Leg has completed orFAILED, onPATCH /api/transactions/{transactionId} - Products and audio (merchant, isv): create_product, get_product, list_products, update_product, delete_product, register_audio, get_audios, get_audio, update_audio, delete_audio
- OAuth2 (isv): obtain_token, get_token_info, rotate_token
- Reports (all, production only): list_reports, generate_report, get_report_status, export_report
- authentication: the JWT helper on its own
payware_generate_documentation
An integration overview for one partner type
Base URLs, how requests are signed, and every operation above that the partner type has, with its route.
Authentication
payware_authentication_generate_rsa_keys
Generate RSA key pair for API authentication.
Parameters:
keySize(optional): RSA key size in bits (default: 2048)
payware_authentication_create_jwt_token
Create JWT token for API authentication.
Parameters:
partnerId(required): Partner ID from paywareprivateKey(required): RSA private key in PEM format
payware_authentication_validate_jwt
Validate JWT token format and signature.
Parameters:
token(required): JWT token to validatepartnerId(required): Partner ID for validation
payware_authentication_test_jwt
Test JWT token with payware API.
Parameters:
token(required): JWT token to testpartnerId(required): Partner ID
payware_authentication_setup_sandbox_auth
Setup sandbox authentication configuration.
Parameters:
partnerId(required): Partner ID from paywareprivateKey(optional): Private key for validation
Transactions
Transaction Status Overview
payware transactions can have the following statuses:
ACTIVE Status:
- ⏳ ACTIVE: Active transaction pending processing or finalizing. Once the payer's institution has started the payment it stays ACTIVE past
timeToLiveuntil the money has moved (seconds for an instant transfer, days withdeferredAllowed), so never infer EXPIRED from the clock - This is the only status returned by
payware_operations_get_transaction_status(a payment institution also seesEXECUTINGon a transaction it has locked) - Use GET
/transactions/{id}endpoint
Final Statuses:
- ✅ CONFIRMED: Successfully finalized
- ❌ DECLINED: Declined by the user, processing or finalizing payment institutions
- 💥 FAILED: Failed due to technical reasons or other
- ⏰ EXPIRED: Time to live of the transaction has passed
- 🚫 CANCELLED: Transaction canceled by the originator
These final statuses are only available through payware_operations_get_transaction_history using GET /transactions-history/{id} endpoint.
payware_operations_create_transaction
Create a new transaction with full API structure support.
Key Parameters:
currency(required): ISO 4217 code payware knows (an unknown code is refused)reasonL1(required): Transaction description (max 100 chars)partnerId(required): Partner ID from payware dashboardprivateKey(required): RSA private key for JWT signingamount(optional): Currency value (default: "0.00" for flexible amounts)type(optional): PLAIN, QR, or BARCODE (default: PLAIN)timeToLive(optional): Payment timeout in seconds, 60-600 (default: 120)deferredAllowed(optional):truelets the payer's institution pay by a credit transfer that settles later; refused with producer or terminal fields (ERR_DEFERRED_TRANSFER_NOT_ALLOWED). A deferred payment stays ACTIVE until it settles, which can take days
QR Options (when type=QR):
qrFormat: PNG, JPG, SVG (default: SVG)qrErrorCorrection: LOW, MEDIUM, QUARTILE, HIGH (default: QUARTILE)qrScale(1-100, default 16),qrBorder(1-10, default 4),qrVersion(1-40, default 3): size and appearance
Barcode Options (when type=BARCODE):
barFormat: PNG, SVG, JPG (default: SVG)barModuleWidth(1-10, default 2),barBarHeight(15-1000, default 100),barFontSize(0-24, default 12),barHumanReadableLocation(NONE, BOTTOM, TOP, default NONE)
payware_operations_get_transaction_status
Get status of ACTIVE transactions only. For completed/finalized transactions use history tool.
Parameters:
transactionId(required): Transaction ID (starts with 'pw')partnerId(required): Partner IDprivateKey(required): Private key for JWT signing
payware_operations_simulate_callback
Simulate callback scenarios for testing.
Parameters:
transactionId(required): Transaction IDstatus(optional): CONFIRMED, DECLINED, FAILED, EXPIRED, or CANCELLED (default: CONFIRMED)callbackUrl(optional): URL where callback would be sentamount(optional): Transaction amount (default: 10.00)currency(optional): Currency (default: EUR)type(optional): Transaction type (default: PLAIN)
Utilities
payware_generate_code_example
Generate a complete program for one payware API call. The operations are listed under Code Generation & Documentation above.
Parameters:
operation(required): the operation, for examplecreate_transactionorfinalize_transactionlanguage(optional): python, nodejs, php, java, csharp, curl (default: python)partner_type(optional): merchant, isv, payment_institution (default: merchant)include_comments(optional): the program with comments, inside a page naming the route (default: true); false gives the program aloneinclude_error_handling(optional): report a failed status or a network error (default: true)
The programs read PAYWARE_PARTNER_ID and PAYWARE_PRIVATE_KEY_PATH (a PKCS#8 PEM), PAYWARE_BASE_URL when set, and for an ISV's call on behalf of a merchant PAYWARE_MERCHANT_PARTNER_ID and PAYWARE_OAUTH2_TOKEN.
payware_generate_documentation
An integration overview for one partner type.
Parameters:
language(optional): the language the next steps refer to (default: python)partner_type(optional): merchant, isv, payment_institution (default: merchant)
payware_utils_format_request
Format and validate API requests with deterministic JSON serialization for SHA-256 consistency.
Parameters:
type(required): transaction, headers, or curldata(optional): Data to formatjwtToken(optional): JWT token for headerssignature(optional): Request signatureendpoint(optional): API endpoint for curlmethod(optional): HTTP method (default: POST)
payware_utils_format_json_deterministic
Format JSON with deterministic property ordering for consistent SHA-256 calculation.
Parameters:
data(required): Object to serializeminimize(optional): Remove whitespace (default: true)
payware_utils_server_info
Get MCP server information and configuration.
Note: All transaction data is serialized using consistent property ordering to prevent content hash mismatch errors.
Dependencies
@modelcontextprotocol/sdk: MCP server frameworkaxios: HTTP client for API callsjsonwebtoken: JWT token creationdotenv: reads.envexpress,cors: the HTTP proxy mode only
RSA keys are generated with Node's own crypto, and multipart uploads use Node's own FormData.
Environment
- Sandbox by default, production on request: tools that call payware take
useSandbox(defaulttrue);falsecalls production and signs with the production key (PAYWARE_PRODUCTION_PRIVATE_KEY_PATH). Reports run on production only. - Base URLs:
https://sandbox.payware.eu/apiandhttps://api.payware.eu/api; the OAuth2 endpoints sit at the host root (/oauth2/...); soundbite recognition has its own hosts,https://soundbite-sandbox.payware.eu/apiandhttps://soundbite.payware.eu/api - Currencies: any ISO 4217 code payware knows; amounts follow the currency's minor unit
- Transaction media types: PLAIN, QR, BARCODE
Security
⚠️ Important Security Notes:
Environment Variables
- REQUIRED: Use environment variables for all credentials
- Never commit
.envfiles to version control - Use different credentials for development and production
- Store private key files outside web-accessible directories
Private Key Security
- Generate separate key pairs for sandbox and production
- Store private keys with restricted file permissions (600)
- Never embed private keys in source code
- Rotate keys regularly according to security policies
API Security
- Calls go to sandbox unless a tool is given
useSandbox: false - Keep sandbox and production keys apart: each environment refuses the other's signature
- Implement proper error handling in production
- Use HTTPS for all API communications
- Validate all input parameters
- Implement rate limiting and monitoring
JSON Serialization & SHA-256 Consistency
⚠️ CRITICAL: payware API requires deterministic JSON serialization for SHA-256 calculation
- Property Order: JSON objects must have consistent property ordering
- Minimized Format: No whitespace or formatting in request bodies
- SHA-256 Calculation: Must be calculated from the exact same JSON string sent to API
- Implementation: This server uses deterministic JSON serialization to ensure consistency
Example of correct JSON format:
{"trData":{"amount":"25.50","currency":"EUR","reasonL1":"Payment description"},"trOptions":{"timeToLive":300,"type":"PLAIN"}}
Why this matters:
- Different property orders produce different SHA-256 hashes
- Hash mismatch results in
ERR_INVALID_CONTENT_HASHerrors - Server validates that JWT
contentSha256matches request body SHA-256
Troubleshooting
Common Issues
-
Authentication Failed (ERR_INVALID_SIGNATURE)
- Root Cause: Public key registered with payware doesn't match your private key
- Solution: Ensure the public key registered on payware site corresponds to your private key
- Verification: Use
openssl rsa -in privateKey.pem -puboutto extract public key from private key - Status: ✅ Resolved - Keys must be properly registered on payware partner portal
-
Content Hash Mismatch Error (ERR_INVALID_CONTENT_HASH)
- Root Cause: Inconsistent JSON property ordering
- Solution: Use deterministic JSON serialization (implemented in this server)
- Symptoms: Server logs show different expected vs actual SHA-256 hashes
- Prevention: Always use
createMinimizedJSON()from/src/core/utils/json-serializer.js - Status: ✅ Fixed - Deterministic JSON serialization implemented
-
Transaction Creation Failed
- Ensure all required parameters are provided
- Check amount is non-negative
- Verify transaction type is supported
- Status: ✅ Working - Create and cancel operations confirmed functional
-
MCP Connection Issues
- Ensure server is started with
npm start - Check that MCP client is properly configured
- Verify no firewall blocking stdio communication
- Note: Use MCP Inspector (
npm run inspector) for debugging
- Ensure server is started with
Proxy and Bridge Tools
HTTP Proxy Server (npm run proxy):
- Bridges MCP tools to HTTP REST API
- Useful for testing tools via HTTP requests
- Documentation:
README-proxy.md
MCP Bridge (npm run bridge):
- Connects MCP server to MCP Inspector
- Essential for debugging and development
- Use with:
npm run inspector
Testing Status
npm test runs every tool of every role against a local fake payware server (no credentials, no network): verb and path against the server's routes, the JWT and its contentSha256, sandbox against production keys, the server's validation rules for the fields the tools send, and the MCP result shape, including isError on a refusal. The fake server is a model of payware, not payware: the suite does not call the real sandbox, so a server change it does not model can still break a tool.
Support
For issues related to:
- MCP Server: Check server logs and MCP client configuration
- payware API: Refer to payware documentation and sandbox status
- Integration: Use code examples and formatting tools provided
- Key Issues: Ensure public key is registered on payware partner portal
License
MIT License
payware MCP Fragen
Wie füge ich payware MCP zu Claude Code hinzu?
Führe claude mcp add --env 'PAYWARE_OAUTH_CLIENT_SECRET=<YOUR_PAYWARE_OAUTH_CLIENT_SECRET>' mcp-server -- npx -y @payware/mcp-server in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich payware MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Kann ich Code-Beispiele für meine Integration generieren?
Ja, der Server kann vollständige, signierte Programme in Python, Node.js, PHP, Java, C# oder curl für echte Routen schreiben.
Wie kann ich die für den KI-Assistenten verfügbaren Tools einschränken?
Du kannst die Umgebungsvariable PAYWARE_MCP_TOOLSETS verwenden, um eine durch Kommata getrennte Liste spezifischer Toolsets wie products oder placements anzugeben.