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:

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.

3. Start the MCP Server

npm start

4. Basic Integration Flow

1. Generate RSA Keys

   Code

   Copy

   Tool: payware_authentication_generate_rsa_keys
   

2. Create JWT Token

   Code

   Copy

   Tool: payware_authentication_create_jwt_token
   
   Parameters:
   
   - partnerId: (from PAYWARE_PARTNER_ID)
   
   - privateKey: (from environment-specific key path)
   

3. Setup Sandbox

   Code

   Copy

   Tool: payware_authentication_setup_sandbox_auth
   
   Parameters:
   
   - partnerId: (from PAYWARE_PARTNER_ID)
   

4. Create Transaction

   Code

   Copy

   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

   Code

   Copy

   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:

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)