Official MCP server for payware payment API integration
npm install @payware/mcp-servercontentSha256 header)
ERR_INVALID_CONTENT_HASH, ERR_MISSING_CONTENT_HASH
bash
npm install -g @payware/mcp-server
`
From source:
`bash
git clone https://github.com/payware/mcp-server.git
cd mcp-server
npm install
`
$3
Copy the example environment file and configure your credentials:
`bash
cp .env.example .env
`
Edit .env file:
`env
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
`bash
npm start
`
$3
1. Generate RSA Keys
`
Tool: payware_authentication_generate_rsa_keys
`
2. Create JWT Token
`
Tool: payware_authentication_create_jwt_token
Parameters:
- partnerId: (from PAYWARE_PARTNER_ID)
- privateKey: (from environment-specific key path)
`
3. Setup Sandbox
`
Tool: payware_authentication_setup_sandbox_auth
Parameters:
- partnerId: (from PAYWARE_PARTNER_ID)
`
4. 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
`
5. 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:
$3
`json
{
// 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)
}
}
`
$3
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
$3
#### 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.
$3
#### 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
$3
#### 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)
$3
#### 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:
$3
- 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
$3
- 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
$3
- 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
$3
โ ๏ธ 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:
`json
{"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
$3
1. 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
2. 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
3. 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
4. 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
$3
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`