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 v1.2.0
- SHA-256 Authentication - Upgraded from MD5 to SHA-256 for JWT content hashing (
contentSha256 header)
- Updated Error Codes - New error codes:
ERR_INVALID_CONTENT_HASH, ERR_MISSING_CONTENT_HASH
- Backward Compatibility - Deprecated MD5 functions retained for legacy support
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
📋 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
- Advanced Code Generation: Generate complete integration code across 8 languages (Python, Node.js, PHP, Java, C#, Go, Ruby, cURL) with 16+ framework support
- Framework Integration: Framework-specific examples for Django, FastAPI, Express, NestJS, Laravel, Spring Boot, ASP.NET, and more
- Real-world Scenarios: Generate complete integration scenarios (e-commerce, ISV multi-merchant, P2P payments)
- Comprehensive Documentation: Auto-generate complete API documentation with code examples
- 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:
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.
3. Start the MCP Server
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, SVG, JPG, GIF, BMP (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: 10, auto if not specified)
},
// 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 | trOptions object | Transaction behavior |
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
Advanced multi-language code generation with framework support
Supports 60+ operations across all partner types:
- Transactions: create_transaction, get_transaction_status, cancel_transaction, process_transaction, get_transaction_history, simulate_callback
- Products: create_product, get_product, update_product, delete_product, list_products, get_product_image, create_schedule, update_schedule, delete_schedule, list_schedules
- OAuth2 (ISV only): obtain_token, get_token_info, create_token_simple, refresh_token, revoke_token, list_active_tokens
- Data: generate_report, get_report_status, export_report, download_export, cancel_report, list_reports, get_analytics_summary, create_custom_report
- Deep Links: get_transaction_link, get_product_link, create_custom_link, delete_transaction_link, delete_product_link, list_active_links, get_link_analytics, create_batch_links
- P2P (Payment Institution): initiate_p2p_transfer, accept_p2p_transfer, reject_p2p_transfer, get_p2p_transfer_status, list_p2p_transfers, cancel_p2p_transfer, create_p2p_link, get_p2p_analytics
- Soundbites (Payment Institution): register_audio, get_audio, update_audio, delete_audio, list_audios, create_soundbite_transaction, stream_audio, download_audio, get_soundbite_analytics, create_audio_playlist, get_audio_preview
payware_generate_documentation
Comprehensive documentation generator
Generates complete API documentation with working code examples for any partner type and programming language combination.
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 payware
privateKey (required): RSA private key in PEM format
payware_authentication_validate_jwt
Validate JWT token format and signature.
Parameters:
token (required): JWT token to validate
partnerId (required): Partner ID for validation
payware_authentication_test_jwt
Test JWT token with payware API.
Parameters:
token (required): JWT token to test
partnerId (required): Partner ID
payware_authentication_setup_sandbox_auth
Setup sandbox authentication configuration.
Parameters:
partnerId (required): Partner ID from payware
privateKey (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
- This is the only status returned by
payware_transactions_get_transaction_status
- 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 3-character code (EUR, USD, GBP, etc.)
reasonL1 (required): Transaction description (max 100 chars)
partnerId (required): Partner ID from payware dashboard
privateKey (required): RSA private key for JWT signing
amount (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)
QR Options (when type=QR):
qrFormat: PNG, SVG, JPG, GIF, BMP (default: SVG)
qrErrorCorrection: LOW, MEDIUM, QUARTILE, HIGH (default: QUARTILE)
qrScale, qrBorder, qrVersion: Size and appearance settings
Barcode Options (when type=BARCODE):
barFormat: PNG, SVG, JPG (default: SVG)
barModuleWidth, barBarHeight, barFontSize: Size settings
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 ID
privateKey (required): Private key for JWT signing
payware_operations_simulate_callback
Simulate callback scenarios for testing.
Parameters:
transactionId (required): Transaction ID
status (optional): CONFIRMED, DECLINED, FAILED, EXPIRED, or CANCELLED (default: CONFIRMED)
callbackUrl (optional): URL where callback would be sent
amount (optional): Transaction amount (default: 10.00)
currency (optional): Currency (default: EUR)
type (optional): Transaction type (default: PLAIN)
Utilities
payware_generate_code_example
Generate production-ready code examples for any payware operation.
Parameters:
operation (required): Operation to generate - see complete list below
language (optional): python, nodejs, php, java, csharp, curl (default: python)
partner_type (optional): merchant, isv, payment_institution (default: merchant)
include_comments (optional): Include detailed code comments (default: true)
include_error_handling (optional): Include comprehensive error handling (default: true)
Available Operations by Category:
Authentication:
authentication - JWT authentication setup
Transaction Operations (all partner types):
create_transaction - Create a new payment transaction
get_transaction_status - Get transaction status and details
process_transaction - Process a pending transaction
cancel_transaction - Cancel a pending transaction
Product Operations (merchant, isv):
create_product - Create a new product
get_product - Get product details
list_products - List all products
POI Operations (isv):
set_price - Set price on a Point of Interaction device
cancel_price - Cancel active price on POI
get_poi - Get POI details
get_poi_status - Get POI transaction status
get_poi_qrcode - Generate QR code for POI
list_pois - List all POIs for a merchant
OAuth2 Operations (isv only):
obtain_token - Obtain OAuth2 access token
get_token_info - Get OAuth2 token information
Data Operations (all partner types):
generate_report - Generate analytics report
get_report_status - Get report generation status
P2P Operations (payment_institution only):
initiate_p2p_transfer - Initiate peer-to-peer transfer
accept_p2p_transfer - Accept P2P transfer
Deep Links (all partner types):
get_transaction_link - Get deep link for transaction
Soundbites (payment_institution only):
register_audio - Register audio content for soundbite transactions
payware_generate_documentation
Generate comprehensive API documentation with code examples.
Parameters:
language (optional): Target programming language (default: python)
partnerType (optional): merchant, isv, payment_institution (default: merchant)
includeScenarios (optional): Include real-world integration scenarios (default: true)
outputFormat (optional): markdown, html, json (default: markdown)
payware_utils_format_request
Format and validate API requests with deterministic JSON serialization for SHA-256 consistency.
Parameters:
type (required): transaction, headers, or curl
data (optional): Data to format
jwtToken (optional): JWT token for headers
signature (optional): Request signature
endpoint (optional): API endpoint for curl
method (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 serialize
minimize (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 framework
axios: HTTP client for API calls
jsonwebtoken: JWT token creation
node-forge: RSA key generation
Environment
- Sandbox Only: All API calls are restricted to sandbox environment
- Base URL:
https://sandbox.payware.eu/api/v1
- Supported Currencies: EUR, USD, GBP
- Supported Transaction Types: PLAIN, QR, BARCODE
Security
⚠️ Important Security Notes:
Environment Variables
- REQUIRED: Use environment variables for all credentials
- Never commit
.env files 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
- This server is designed for sandbox testing only
- Never use sandbox keys in production environment
- 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_HASH errors
- Server validates that JWT
contentSha256 matches 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 -pubout to 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
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
✅ Confirmed Working Operations:
- JWT token creation with RS256 algorithm
- Transaction creation (POST /api/transactions)
- Transaction cancellation (PATCH /api/transactions/{id})
- Deterministic JSON serialization for SHA-256 consistency
- Public/private key pair validation
🧪 Test Results:
- All MCP tools tested successfully with real payware sandbox API
- Both create and cancel transaction flows working end-to-end
- Signature validation resolved with proper key registration
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