# payware (npm · @payware/mcp-server)

payware A2A payments API for merchants, ISVs, payment institutions and buying agents

- Trust score: 77/100 (medium)
- Change this week: +12
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-22

## Components

- npm · `@payware/mcp-server`: 77/100 (this document), [markdown](https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server.md), [page](https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@payware/mcp-server`
- Version: `2.6.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-22.

- **Supply Chain Security**: 48/100
  - Malware scan not yet available for this package.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 43 of 120 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to payware/mcp-server).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 57/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 23424 tokens (~296/item across 79 items; 79 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 99/100
  - Stability check failed: the tool surface changed between 2.0.0 and 2.6.0: 0 tool removals, 1 breaking changes, 12 additions.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 6 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 79 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the payware MCP server?

payware runs locally as an npm package, launched with npx -y @payware/mcp-server. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add payware-mcp-server -- npx -y @payware/mcp-server
```

### Cursor

```json
{
  "mcpServers": {
    "payware-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@payware/mcp-server"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "payware-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@payware/mcp-server"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add payware-mcp-server -- npx -y @payware/mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "payware-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@payware/mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add payware-mcp-server --command npx --arg -y --arg @payware/mcp-server
```

### Hermes

```yaml
mcp_servers:
  payware-mcp-server:
    command: "npx"
    args: ["-y", "@payware/mcp-server"]
```

### Netclaw

```json
{
  "McpServers": {
    "payware-mcp-server": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@payware/mcp-server"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add payware-mcp-server -t stdio -c npx -a -y @payware/mcp-server
```

### Other

```json
{
  "mcpServers": {
    "payware-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@payware/mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-22 (score 77, −4)

- [security regression] Malware scan: pass → unverified
- [security improvement] Provenance: fail → pass
- [security] The attested source repository moved: payware/mcp-server
- [functional improvement] Security disclosure: fail → pass
- [functional] Package version: 2.5.0 → 2.6.0

### 2026-11-21 (score 81, +1)

No change was recorded against any check on this day. Stability & Change Management went from 92 to 99.

### 2026-11-19 (score 80, +15)

- [security regression] Stability: fail → unverified
- [security regression] Tool safety: pass → unverified
- [security improvement] Malware scan: unverified → pass
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional] Package version: 2.4.0 → 2.5.0

### 2026-11-18 (score 65, −15)

- [security regression] Malware scan: pass → unverified
- [functional] Package version: 2.3.0 → 2.4.0

### 2026-11-16 (score 80, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-15 (score 65, −15)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 19669 → 22026
- [functional] Package version: 2.2.2 → 2.3.0

### 2026-11-14 (score 80, +11)

- [security improvement] Known CVEs: unverified → pass
- [functional improvement] Dependency health: unverified → 0.84

### 2026-11-13 (score 69, −10)

- [security regression] Stability: fail → unverified
- [security regression] Known CVEs: pass → unverified
- [security regression] Tool safety: pass → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Dependency health: 0.84 → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional] Package version: 1.5.0 → 2.2.2
- [functional] Package version: 2.2.1 → 2.2.2

## MCP tools (79)

### `payware_authentication_generate_rsa_keys` (~40 tokens)

[Merchant] Generate RSA key pair for payware API authentication

Input parameters:

- `keySize` (number): RSA key size in bits

### `payware_authentication_create_jwt_token` (~179 tokens)

[Merchant] Create JWT token for payware API authentication according to official documentation

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key - accepts PEM format with/without headers or raw base64 content. Uses environment-specific private key as default.
- `requestBody` (object|string): Request body for a POST, PUT or PATCH, which then needs contentSha256. An object is serialized once (keys sorted, no spaces) and the result shows that exact string: send it byte for byte. A string is…
- `useSandbox` (boolean): Sign with the sandbox key (default) or the production key; a token signed with one environment's key is refused by the other

### `payware_authentication_validate_jwt` (~136 tokens)

[Merchant] Validate and debug a payware JWT: decode header and payload, check the claims against the API's rules (algorithm, audience including the ISV on-behalf form, 5-minute freshness), and verify the contentSha256 hash against the request body when one is given

Input parameters:

- `expectedPayload` (object): The request body the token was made for (optional). Give it for POST, PUT and PATCH: contentSha256 is then required and checked against it. Leave it out for GET and DELETE, which carry no hash.
- `jwtToken` (string, required): JWT token to validate and debug

### `payware_authentication_test_jwt` (~116 tokens)

[Merchant] Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, SHA-256 hash calculation, and final JWT structure

Input parameters:

- `partnerId` (string): Partner ID for JWT creation (defaults to environment)
- `requestPayload` (object): Sample request payload to demonstrate SHA-256 hash calculation
- `showPrivateKey` (boolean): Whether to show private key details (for debugging)
- `useSandbox` (boolean): Use the sandbox key (default) or the production key

### `payware_authentication_setup_sandbox_auth` (~78 tokens)

[Merchant] Setup sandbox authentication configuration for payware API

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key in PEM format (optional, for validation). Uses environment-specific private key as default.

### `payware_generate_code_example` (~435 tokens)

[Merchant] Generate a complete program for one payware API call, or the JWT helper, in python, nodejs, php, java, csharp, curl. Each program signs its request as payware requires (RS256 JWT with contentSha256 for a body, on behalf of a merchant for an ISV) and calls the real route. finalize_transaction (payment institutions) is the whole institution flow: process, EXECUTING immediately before money moves, then CONFIRMED once the Merchant Leg has completed, or FAILED.

Input parameters:

- `include_comments` (boolean): true (default): the program with comments, inside a page that names the route and what to know about it. false: the program alone.
- `include_error_handling` (boolean): true (default): report a failed status or a network error. false: the shortest program.
- `language` (string): python (requests, PyJWT), nodejs (axios, jsonwebtoken), php (cURL, firebase/php-jwt), java (Java 11 HttpClient, no dependencies), csharp (.NET 6 HttpClient, no dependencies) or curl (curl and openssl…
- `operation` (string, required): The operation. Transactions: create_transaction, get_transaction_status, process_transaction, cancel_transaction, get_transaction_history, and for payment_institution finalize_transaction (process, E…
- `partner_type` (string): merchant, isv (calls on behalf of a merchant, and the OAuth2 token endpoints) or payment_institution. Decides which operations exist and how the JWT is signed. Default merchant.

### `payware_generate_documentation` (~108 tokens)

[Merchant] An integration overview for one partner type: base URLs, how requests are signed, and every operation payware_generate_code_example can write, with its route.

Input parameters:

- `language` (string): The language the overview's next steps refer to: python, nodejs, php, java, csharp, curl. Default python.
- `partner_type` (string): merchant, isv or payment_institution. Decides the operations listed and how requests are signed. Default merchant.

### `payware_utils_format_request` (~94 tokens)

[Merchant] Format and validate payware API requests with proper structure and headers

Input parameters:

- `data` (object): Data to format (structure depends on type)
- `endpoint` (string): API endpoint URL (for curl formatting)
- `jwtToken` (string): JWT token for header formatting
- `method` (string): HTTP method (for curl formatting)
- `type` (string, required): Type of formatting to perform

### `payware_utils_server_info` (~40 tokens)

[Merchant] Get MCP server version, status, and environment information

Input parameters:

- `includeEnvironment` (boolean): Include environment details (default: true)

### `payware_utils_format_json_deterministic` (~102 tokens)

[Merchant] Format JSON payload with deterministic key sorting for consistent SHA-256 calculation and payware API compliance

Input parameters:

- `calculateSHA256` (boolean): Calculate SHA-256 hash for JWT contentSha256 usage
- `payload` (object, required): JSON payload to format with deterministic serialization
- `showComparison` (boolean): Show comparison between standard and deterministic JSON
- `validateConsistency` (boolean): Validate that multiple serializations produce the same result

### `payware_operations_create_transaction` (~3436 tokens)

[Merchant] Create a new payware transaction. Parameters map to the following API structure:

📋 **ROOT LEVEL** (Transaction metadata):
\- shop, account, friendlyName, callbackUrl, passbackParams
\- producerPartnerId, terminalId, terminalManufacturer (POS terminal producer attribution - see below)

💰 **TRANSACTION DATA** (trData object):
\- amount, currency, reasonL1, reasonL2, tip (your own tip inside amount - see below)

⚙️ **TRANSACTION OPTIONS** (trOptions object):
\- type, timeToLive (see below), deferredAllowed (deferred Merchant Leg opt-in - see below)

📱 **QR OPTIONS** (qrOptions object - only when type=QR):
\- qrFormat, qrBorder, qrErrorCorrection, qrScale, qrVersion

🔗 **BARCODE OPTIONS** (barOptions object - only when type=BARCODE):
\- barFormat, barModuleWidth, barBarHeight, barFontSize, barHumanReadableLocation

🔐 **AUTHENTICATION** (not sent to API, used for JWT signing):
\- partnerId, privateKey

\**Actual API Request Structure:**
\```json
{
  "shop": "...",
  "account": "...",
  "friendlyName": "...",
  "callbackUrl": "...",
  "passbackParams": "...",
  "trData": {
    "amount": "25.50",
    "currency": "EUR", 
    "reasonL1": "...",
    "reasonL2": "..."
  },
  "trOptions": {
    "type": "QR",
    "timeToLive": 300
  },
  "qrOptions": { ... }
}
\```

🧾 **LINES** (`items`, root level, optional): what the payer's bank shows instead of one amount - items with quantity and unit price, delivery, discounts, taxes. 1-50 lines that sum exactly to `trData.amount`, or to `trData.amount` minus `tip` when you send one (400 `ERR_ITEMS_DO_NOT_SUM`); malformed lines, or a line with a `country` (payware sets it only on delivery lines it prices), are 400 `ERR_INVALID_ITEMS`; an empty list is 400 `ERR_ITEMS_EMPTY` (leave `items` out instead). Not for an amount of 0. Every payment, with lines or without, is paid exactly the amount it asks (the payer's bank gets 409 `ERR_AMOUNT_NOT_TOTAL` for anything else), plus a tip where one is allowed. A tip is never a line: a `TIP` li…

Input parameters:

- `account` (string): 📋 ROOT LEVEL: Account identifier (if not supplied, determined from payware portal)
- `amount` (number): Amount as currency value (e.g., 25.50 for €25.50 or '15.75' for $15.75). Can be 0 for amount-flexible transactions. At most 15 significant digits and 15 integer digits (400 ERR_INVALID_AMOUNT_LENGTH)
- `barBarHeight` (number): BARCODE OPTIONS (type=BARCODE): bar height in pixels, 15-1000 (default 100)
- `barFontSize` (number): BARCODE OPTIONS (type=BARCODE): font size of the human-readable text, 0-24 (default 12)
- `barFormat` (string): BARCODE OPTIONS (type=BARCODE): image format, PNG, JPG or SVG (default SVG)
- `barHumanReadableLocation` (string): BARCODE OPTIONS (type=BARCODE): where the human-readable text goes (default NONE)
- `barModuleWidth` (number): BARCODE OPTIONS (type=BARCODE): module width in pixels, 1-10 (default 2)
- `callbackUrl` (string): 📋 ROOT LEVEL: HTTPS URL to receive transaction status callbacks. Must be https://, must present a publicly-trusted TLS certificate, and must resolve to a public address - internal/private addresses…
- `currency` (string, required): Transaction currency (ISO 3-character code)
- `deferredAllowed` (boolean): ⚙️ TRANSACTION OPTIONS: Opt this transaction in to a deferred Merchant Leg (sent as trOptions.deferredAllowed). Optional; omit it for instant or internal only. When true, the payer's institution may…
- `friendlyName` (string): 📋 ROOT LEVEL: Account holder recognizable name (if not supplied, merchant alias is used)
- `idempotencyKey` (string): Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the tra…
- `items` (array): Optional lines the payer's bank shows, 1 to 50, e.g. [{"type":"ITEM","name":"Vase","quantity":2,"unitPrice":"40.00","amount":"80.00"},{"type":"SHIPPING","name":"Delivery","amount":"5.00"}]. The lines…
- `partnerId` (string): 🔐 AUTHENTICATION: Partner ID from payware dashboard (not sent in API request). Uses PAYWARE_PARTNER_ID env var as default.
- `passbackParams` (string): 📋 ROOT LEVEL: Additional parameters passed back in callbacks (max 200 chars)
- `privateKey` (string): 🔐 AUTHENTICATION: RSA private key for JWT token creation (not sent in API request). Accepts PEM format with/without headers or raw base64 content. Uses environment-specific private key as default.
- `producerPartnerId` (string): 🏭 ROOT LEVEL: partnerId of the POS terminal producer whose terminal produced this transaction. Must be a partner registered with payware and flagged as a producer - an unrecognised value REJECTS the…
- `qrBorder` (number): QR OPTIONS (type=QR): quiet zone around the code, in modules, 1-10 (default 4)
- `qrErrorCorrection` (string): QR OPTIONS (type=QR): error correction, LOW (7%), MEDIUM (15%), QUARTILE (25%) or HIGH (30%) (default QUARTILE)
- `qrFormat` (string): QR OPTIONS (type=QR): image format, PNG, JPG or SVG (default SVG)
- `qrScale` (number): QR OPTIONS (type=QR): pixels per module, 1-100, irrelevant for SVG (default 16)
- `qrVersion` (number): QR OPTIONS (type=QR): QR version, 1-40, higher holds more data (default 3)
- `reasonL1` (string, required): Transaction grounds description (required)
- `reasonL2` (string): Transaction grounds description continuation (optional)
- `shop` (string): 📋 ROOT LEVEL: Shop code (if not supplied, default shop is used)
- `terminalId` (string): 🏭 ROOT LEVEL: Opaque identifier of the physical terminal, scoped to the producer's own estate. payware assumes no format and enforces no uniqueness; it is recorded for provenance and never affects a…
- `terminalManufacturer` (string): 🏭 ROOT LEVEL: Device manufacturer as reported by the terminal. Recorded for provenance; a mismatch against the expected producer is surfaced in settlement review and never blocks the transaction. No…
- `timeToLive` (number): ⚙️ TRANSACTION OPTIONS: Time allowed for payment initiation in seconds (sent as trOptions.timeToLive; 120 when left out). payware accepts 60 up to the merchant's own ceiling: 600 by default, which th…
- `tip` (string|number): 💰 TRANSACTION DATA: your own tip inside amount, sent as trData.tip, e.g. "2.00": a tip the payer chose at your till before you showed the code. A plain decimal above 0 at the currency's scale, at mo…
- `type` (string): Transaction type
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_operations_get_transaction_status` (~960 tokens)

[Merchant] Get status of an ACTIVE transaction by ID (for completed/expired transactions use transaction history tool).

\**Endpoint:** GET /transactions/{transactionId}
\**Use Case:** Check status of ACTIVE transactions only. This endpoint only returns transactions with ACTIVE status.
\**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_operations_get_transaction_history' instead.

⏳ **ACTIVE can outlast `timeToLive`. Never infer EXPIRED from the clock.** Once the payer's institution has
started the payment (it locks the transaction immediately before the money moves, which you do not see),
the transaction stays ACTIVE past `timeToLive` until the money has moved: seconds for an instant or
internal transfer, days for a deferred one (a transaction created with `deferredAllowed: true`). Its
\`timeToLive` then stops at the value it had when the payment started. Keep polling, or wait for the
callback: a transaction is EXPIRED only when payware says so, in the callback or in transaction history,
and one that is no longer returned here has a final status there.

🛍️ **Product-originated transactions carry a nested `product` object.** Since 2026-07-22 the
presentation fields are grouped under `product` rather than sitting flat on the response - the old
top-level `imageUrl` is gone. Discriminate a product-originated transaction by the **presence of the
object**, not by probing individual fields:

\```json
{ "transactionId": "pw7e4rCToG", "amount": "57.60", "currency": "EUR",
  "product": { "productId": "pr7e4rCToG", "type": "ITEM", "name": "Cotton T-shirt, black",
               "shortDescription": "...", "longDescription": "...",
               "imageUrl": "https://...", "imageDigest": "9f86d081...", "imageContentType": "image/png",
               "imageBytes": 20480, "termsUrl": "https://...", "termsText": "...",
               "regularPrice": "63.36", "shippable": false, "quickPay": true, "shopName": "My shop" } }
\``…

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Can use PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.
- `transactionId` (string, required): Transaction ID to check status for
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_operations_cancel_transaction` (~179 tokens)

[Merchant] Cancel an ACTIVE transaction created by this merchant. Only the merchant who created the transaction can cancel it, and only before it has been processed.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Can use PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.
- `statusMessage` (string, required): Reason for cancellation (required)
- `transactionId` (string, required): Transaction ID to cancel (must be an ACTIVE 'pw' transaction created by this merchant). Format: 'pw' + 8 characters. Product ('pr') and soundbite ('ps') ids are NOT cancellable - deactivate those thr…
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_operations_get_transaction_history` (~634 tokens)

[Merchant] Get history of completed/finalized transactions with final statuses.

\**Endpoint:** GET /transactions-history/{transactionId}
\**Use Case:** Retrieve transactions with final statuses: CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED.
\**Note:** For ACTIVE transactions, use 'payware_operations_get_transaction_status' instead.

📦 **This is where the delivery address lives.** For a SHIPPABLE transaction, `deliveryAddress`
(fullName, streetAddressLine1/2, zipCode, city, region, country, phoneNumber, email) is returned
here and **only** here. It was removed from the finalized callback on 2026-08-07: a callback is
pushed to whatever URL is registered and its body stays in request logs and retry queues, which is
acceptable for a transaction id and an amount and not for a shopper's home address. This endpoint is
JWT-authenticated with your own credentials and tenant-scoped. So the pattern is: the callback
tells you the shipment is ready, and this call gives you the address to ship to.

🧾 **Lines and tip.** A payment with lines carries `items` and `total`: what was sold. A tip is never
a line: `tip` (absent without one) is yours, sent when you created the payment, or the payer's,
added in their bank where your shop allows tips; `tipEnteredBy` (`MERCHANT` or `PAYER`) says which. The payer paid `total` + `tip`.

⚠️ **Requires Standard or Premium.** This endpoint was ungated until 2026-08-21 and is now on the
same plan gate as the rest of the transaction surface, so a **Basic** merchant - or an ISV acting on
behalf of one - now gets **403**. If reading history started failing without a code change, this is
why. Financial institutions are unaffected; banks are always Premium.

⏱️ **Rate limited, like every payware endpoint.** A 429 carries `ERR_RATE_LIMIT_EXCEEDED` and a
\`Retry-After` header, in seconds; the request was not processed, so the identical request is safe to
retry once the window passes. The failure result exposes this as `error.throttled`,
\`error.retryabl…

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Can use PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.
- `transactionId` (string, required): The pw transaction id. History looks the id up as given, so a product, placement, soundbite or POI id is not found: use the pw id the process response returned. Up to 32 characters (identifiers may g…
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_operations_process_transaction` (~627 tokens)

[Merchant] Process a PEER transaction (for merchants accepting payments by scanning customer QR/barcode).

\**Use Case:** Merchant scans customer's payware QR code or barcode to accept payment.
\**Note:** Only PEER transactions (created by customers) can be processed by merchants.
\**Flow:** Customer creates transaction → Merchant scans QR/barcode → Merchant processes transaction

\**API Request Structure:**
\```json
{
  "shop": "...",
  "account": "...", 
  "friendlyName": "...",
  "callbackUrl": "...",
  "passbackParams": "...",
  "trData": {
    "amount": "25.50",    // REQUIRED for processing
    "currency": "EUR",    // REQUIRED for processing
    "reasonL1": "...",    // REQUIRED for processing
    "reasonL2": "..."
  },
  "trOptions": {
    "timeToLive": 300     // Overwrites original transaction TTL
  }
}
\```

Input parameters:

- `account` (string): Account identifier (optional - uses default if not provided)
- `amount` (number|string, required): Amount as currency value to process (e.g., 25.50 for €25.50). Must be positive
- `callbackUrl` (string): URL to receive transaction status callbacks
- `currency` (string, required): Transaction currency (ISO 3-character code)
- `friendlyName` (string): Account holder recognizable name (optional)
- `idempotencyKey` (string): Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the tra…
- `partnerId` (string): Partner ID from payware dashboard. Can use PAYWARE_PARTNER_ID env var as default.
- `passbackParams` (string): Parameters passed back through callback
- `privateKey` (string): RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.
- `reasonL1` (string, required): Transaction grounds description (required)
- `reasonL2` (string): Transaction grounds description continuation (optional)
- `shop` (string): Shop code (optional - uses default if not provided)
- `timeToLive` (number): Time allowed for transaction processing in seconds
- `transactionId` (string, required): Transaction ID to process: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite). Up to 32 characters (identifiers m…
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_operations_simulate_callback` (~1571 tokens)

[Merchant] Simulate callback scenarios for testing webhook handling.

Generates the payload a merchant's `callbackUrl` actually receives, so a handler can be built and
tested against the real shape. Four properties of that shape are easy to get wrong:

\**1. Absent means absent, not zero.** The payload omits properties with no value rather than sending
\`null` or `0`. `statusMessage`, `passbackParams`, `fee`, `feeFixed` and `feeRate` are all simply
missing when they do not apply. A missing `fee` means the fee is *unknown* for that transaction - it
does not mean the transaction was free. Do not write a handler that reads `payload.fee` as a number
without checking it is there.

\**2. `finalized` is absent on EXPIRED.** An expired transaction is closed by the platform's expiry
sweep, which sets no finalization moment. Every other status carries one.

\**3. `EXPIRED` is a non-payment, not a failure.** The payer never paid within `timeToLive`. Release
the order or the stock, as you would for a cancellation - do not treat it as an error to retry.

\**4. Deduplicate on `(transactionId, callbackType)`.** payware retries a callback up to 15 times,
backing off from about a second to at most 5 minutes between attempts, until the endpoint answers any
2xx. That pair is stable across every retry of the same event, and it is the key payware guarantees.
A handler that does not deduplicate will eventually process one payment twice.

\**Payments with a product, a placement, a session or lines.** The payload also carries, when they apply and absent otherwise: `productId` (the product the payment came from), `placementId` (the placement it is attributed to, Premium only), `sessionId` (the purchase session's pa id) and `items` with their `total` (type, productId, name, quantity, unitPrice, amount, and country on a delivery line payware priced; no images). `total` is the sum of the lines, what was sold. **A tip is never a line**: the payload carries it as `tip` (absent without one), yours, se…

Input parameters:

- `amount` (string): Transaction amount (e.g., '57.60'; that is the default without items). With items leave it out: on CONFIRMED it is total minus fee, on any other status the total; a different value is refused
- `callbackUrl` (string): URL where callback would be sent (for simulation only)
- `currency` (string): Transaction currency
- `fee` (string): payware's fee on this transaction plus VAT where it applies, at the currency's smallest payable unit (e.g. '0.29'). The payer's institution transfers it to payware alongside the merchant's payment, a…
- `feeFixed` (string): Fixed fee component of the applicable fee configuration, e.g. '0.1000'. Informational, for reconciliation. Present on FINALIZED callbacks since 2026-08-21 - before that a merchant got the total fee b…
- `feeRate` (string): Variable rate of the applicable fee configuration, e.g. '0.0150' = 1.5%. Informational, same as feeFixed. Pass null to model a transaction with no fee configuration.
- `feeVat` (string): The VAT included in fee (fee minus feeVat is payware's fee excluding VAT), at the same scale; zero when no VAT applies (reverse charge, or a merchant outside the EU). Present exactly when fee is (ser…
- `items` (array): Lines of a payment that has them (a product payment with a quantity, a purchase session, a merchant payment created with items): the callback then carries items and their total (the sum of the lines:…
- `paymentMethod` (string): Payment method chosen by customer. A2A = direct transfer. CARD_FUNDED = card-linked account. BNPL = buy now pay later. INSTANT_CREDIT = credit line.
- `placementId` (string): Set to simulate a payment attributed to a placement (Premium merchants): the callback then carries the placementId
- `poiId` (string): Set to simulate a POI sale: the callback then carries the poiId of the POI that created the transaction
- `productId` (string): Set to simulate a payment that came from a product: the callback then carries the productId (from the product snapshot)
- `sessionId` (string): Set to simulate a payment that came from an agent purchase session: the callback then carries the session's pa id
- `status` (string): Transaction status to simulate
- `statusMessage` (string): Custom status message for the transaction callback
- `tip` (string): The payment's tip, a decimal string (e.g. '2.00'): the merchant's own, sent when it created the payment, or the payer's, added in their bank where the shop allows tips. Never a line: the callback car…
- `tipEnteredBy` (string): With tip: who entered it, MERCHANT (on create) or PAYER (in the bank app). Default PAYER. The callback carries it only with a tip.
- `transactionId` (string, required): Transaction ID to simulate callback for

### `payware_data_list_reports` (~88 tokens)

[Merchant] List all available report types with their configurations, descriptions, and visibility settings. Production only - not supported in sandbox.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).

### `payware_data_generate_report` (~609 tokens)

[Merchant] Generate an asynchronous data report for merchant data analysis and reporting. Production only - not supported in sandbox.

⚠️ **Running a report is entitlement-checked as of 2026-08-22.** Naming a report answers **403
\`ERR_REPORT_NOT_AVAILABLE`** when that report is not included in the caller's plan or partner type.
Until that date only the *menu* was filtered - the door was not - so a caller that hard-coded a
report id it had never been offered could still run it, and may now start failing.

\**Always resolve the id from `payware_data_list_reports` rather than hard-coding one.** That call
and this check share a single rule, so the menu and the door cannot drift apart: if a report is in
that list, this call will accept it.

Distinguish the two failures:
\- **403 `ERR_REPORT_NOT_AVAILABLE`** - the report exists, this caller may not run it. Not retryable;
  it is a plan boundary, not a transient error.
\- **404 `ERR_REPORT_UNIT_ID_NOT_FOUND`** - no report is registered under that id at all. Usually a
  typo or a stale id.

For an ISV acting on behalf of a merchant, the plan that applies is the **merchant's**, and reports
are outside the Basic plan entirely.

Input parameters:

- `dateFrom` (string): Start date (YYYY-MM-DD), with period CUSTOM or no period. Ignored with any other preset.
- `dateTo` (string): End date (YYYY-MM-DD), with period CUSTOM or no period. Only an end date covers that one day; no end on a range is today.
- `ignorePagination` (boolean): If true, return report as single continuous document. If false, paginate results.
- `locale` (string): Locale for the report
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `period` (string): Period preset: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_QUARTER, LAST_QUARTER, THIS_YEAR, LAST_YEAR, or CUSTOM with dateFrom (and dateTo for a range). Which presets a repo…
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).
- `reportUnitId` (string, required): The ID of the report to generate
- `timeZone` (string): Timezone for date calculations (e.g., 'Europe/Sofia', 'America/New_York')

### `payware_data_get_report_requests` (~124 tokens)

[Merchant] Get all execution requests for a specific report type. Returns historical execution records with status and parameters. Production only - not supported in sandbox.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).
- `reportId` (string, required): The report id whose runs to list, bare (processedTransactions) or as the path the list returns (/processedTransactions)

### `payware_data_get_report_status` (~103 tokens)

[Merchant] Get the status of an asynchronous report generation request. Use this to monitor report progress.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).
- `requestId` (string, required): The request ID returned from the report generation request (UUID format)

### `payware_data_export_report` (~119 tokens)

[Merchant] Export a READY report in a specific format (PDF, CSV, Excel, JSON). The report must be in READY status first.

Input parameters:

- `outputFormat` (string): Export format
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).
- `requestId` (string, required): The request ID from the report generation (UUID format)

### `payware_data_get_export_list` (~116 tokens)

[Merchant] Get all export attempts for a specific report request. Returns list of exports in various formats with their status and download information. Production only - not supported in sandbox.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses production private key as default (Data API is production-only).
- `requestId` (string, required): The request ID (UUID) to get exports for

### `payware_data_get_export_status` (~96 tokens)

[Merchant] Get the status of a report export request. Use this to monitor export progress.

Input parameters:

- `exportId` (string, required): The export ID returned from the export request (UUID format)
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.

### `payware_data_download_export` (~203 tokens)

[Merchant] Download a READY export file (production only). A text export (CSV, HTML, XML) is previewed; with saveToFile the file is written to payware-mcp-downloads in the system temp directory and the result names its path. A binary export (PDF, XLS(X), DOCX, ODT, ODS, RTF) needs saveToFile.

Input parameters:

- `exportId` (string, required): The export ID from the export request (UUID format)
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses the production private key as default (reports run on production only).
- `saveToFile` (boolean): Save the file to payware-mcp-downloads in the system temp directory and return its path. Without it a text export is previewed and a binary one only described.

### `payware_data_cancel_report` (~96 tokens)

[Merchant] Cancel a running report generation. Only reports in QUEUED status can be cancelled.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.
- `requestId` (string, required): The request ID of the report to cancel (UUID format)

### `payware_data_cancel_export` (~96 tokens)

[Merchant] Cancel a running export process. Only exports in QUEUED status can be cancelled.

Input parameters:

- `exportId` (string, required): The export ID of the export to cancel (UUID format)
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.

### `payware_products_create_product` (~518 tokens)

[Merchant] Create a new product for inventory management and payment processing.

\**Product Structure:**
📦 **PRODUCT METADATA**: name, shortDescription, longDescription, sku, upc, shippable, active, shop
💰 **PRODUCT DATA** (prData object): type, regularPrice, currency, overlapPriority, timeToLive, activeFrom, activeTo, timeZone
⚙️ **PRODUCT OPTIONS** (prOptions object): imageUrl, termsUrl, termsText

\**Required:** name
\**Optional:** All other parameters have sensible defaults

Input parameters:

- `active` (string): Indicates if product can serve as payment source
- `activeFrom` (string): Product active state starting date (YYYY-MM-DD format)
- `activeTo` (string): Product active state ending date (YYYY-MM-DD format)
- `currency` (string): Price currency (3-character ISO code)
- `imageUrl` (string): URL pointing to external product image resource
- `longDescription` (string): Long product description
- `name` (string, required): Product recognizable name (required)
- `overlapPriority` (string): Priority when overlapping price schedules exist
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productType` (string): Type of product
- `regularPrice` (string): Product regular price as a decimal string. Zero or positive, at most 12 integer digits, and no more decimals than the currency's minor unit (0 for JPY, 2 for EUR, 3 for KWD, 8 for BTC). Returned as a…
- `shippable` (string): Indicates if product requires delivery address
- `shop` (string): Shop code (if not supplied, default shop is used)
- `shortDescription` (string): Short product description
- `sku` (string): Stock Keeping Unit (SKU)
- `termsText` (string): Terms and conditions text
- `termsUrl` (string): URL pointing to external terms and conditions resource
- `timeToLive` (number): Time allowed for product payment in seconds (60-2592000)
- `timeZone` (string): Product state scheduling timezone (IANA format, e.g., 'Europe/Sofia')
- `upc` (string): Universal Product Code (UPC)
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_list_products` (~79 tokens)

[Merchant] Get a list of all products for the merchant account

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_product` (~93 tokens)

[Merchant] Get detailed information about a specific product by ID

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_update_product` (~742 tokens)

[Merchant] Update an existing product. Only provide the fields you want to change: payware keeps every stored value the request leaves out. With neither activeFrom nor activeTo the active period stays as stored; with one of them the other is worked out as on create (activeFrom alone: the period runs one year from it; activeTo alone: it starts one year before activeTo, or today if that is later), and a start before today is refused (ERR_INVALID_ACTIVE_FROM_DATE).

\**Product Structure:**
📦 **PRODUCT METADATA**: name, shortDescription, longDescription, sku, upc, shippable, active, shop
💰 **PRODUCT DATA** (prData object): type, regularPrice, currency, overlapPriority, timeToLive, activeFrom, activeTo, timeZone
⚙️ **PRODUCT OPTIONS** (prOptions object): imageUrl, termsUrl, termsText

\**Changing `currency`** of a product with delivery settings is refused, and nothing changes, rather than quietly changing what delivery costs (VG 2026-11-15): 409 `ERR_PRODUCT_CURRENCY_HAS_SURCHARGES` while the product has delivery surcharges (they are amounts in its current currency: clear them with `payware_products_set_delivery`, keeping the exclusions, change the currency, then enter them again in the new one), checked first; and 409 `ERR_NO_DELIVERY_IN_CURRENCY` for a shippable product whose shop's delivery table has no rows in the new currency, which would leave it deliverable nowhere (add them with `payware_shops_set_delivery` first).

Input parameters:

- `active` (string): Indicates if product can serve as payment source
- `activeFrom` (string): Product active state starting date (YYYY-MM-DD format)
- `activeTo` (string): Product active state ending date (YYYY-MM-DD format)
- `currency` (string): Price currency (3-character ISO code)
- `imageUrl` (string): URL pointing to external product image resource
- `longDescription` (string): Long product description
- `name` (string): Product recognizable name
- `overlapPriority` (string): Priority when overlapping price schedules exist
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier to update (starts with 'pr')
- `productType` (string): Type of product
- `regularPrice` (string): Product regular price as a decimal string. Zero or positive, at most 12 integer digits, and no more decimals than the currency's minor unit (0 for JPY, 2 for EUR, 3 for KWD, 8 for BTC). Returned as a…
- `shippable` (string): Indicates if product requires delivery address
- `shop` (string): Shop code
- `shortDescription` (string): Short product description
- `sku` (string): Stock Keeping Unit (SKU)
- `termsText` (string): Terms and conditions text
- `termsUrl` (string): URL pointing to external terms and conditions resource
- `timeToLive` (number): Time allowed for product payment in seconds (60-2592000)
- `timeZone` (string): Product state scheduling timezone (IANA format, e.g., 'Europe/Sofia')
- `upc` (string): Universal Product Code (UPC)
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_delete_product` (~99 tokens)

[Merchant] Delete a product from the merchant account. This action cannot be undone.

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier to delete (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_product_image` (~356 tokens)

[Merchant] Generate a QR code or barcode image for a product.

\**QR Code Options:** Format, border, error correction, scale, version
\**Barcode Options:** Format, module width, bar height, font size, text location

Input parameters:

- `barBarHeight` (number): Barcode height in pixels (applies when type=BARCODE)
- `barFontSize` (number): Barcode font size in pixels (applies when type=BARCODE)
- `barFormat` (string): Barcode image format (applies when type=BARCODE)
- `barHumanReadableLocation` (string): Barcode text position (applies when type=BARCODE)
- `barModuleWidth` (number): Barcode module width in pixels (applies when type=BARCODE)
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `qrBorder` (number): QR code border size in modules (applies when type=QR)
- `qrErrorCorrection` (string): QR code error correction level (applies when type=QR)
- `qrFormat` (string): QR code image format (applies when type=QR)
- `qrScale` (number): QR code module size in pixels, irrelevant for SVG (applies when type=QR)
- `qrVersion` (number): QR code version, higher versions store more data (applies when type=QR)
- `type` (string): Type of image to generate
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_create_schedule` (~205 tokens)

[Merchant] Create a price schedule for a product to manage time-based pricing. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `correctionType` (string): Price correction method
- `correctionValue` (string): Correction value (positive number with max 2 decimals)
- `dateFrom` (string): Schedule start date (YYYY-MM-DD format)
- `dateTo` (string): Schedule end date (YYYY-MM-DD format)
- `description` (string): Schedule description
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `priceCorrection` (string): Price correction direction
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_schedules` (~120 tokens)

[Merchant] Get all price schedules for a product. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_schedule` (~130 tokens)

[Merchant] Get detailed information about a specific price schedule. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `scheduleId` (number, required): Schedule identifier
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_update_schedule` (~301 tokens)

[Merchant] Update an existing price schedule. Only provide the fields you want to change: payware keeps every stored value the request leaves out. With neither dateFrom nor dateTo the schedule's period stays as stored; with one of them the other is worked out as on create (dateFrom alone: the period runs one month from it; dateTo alone: it starts one month before dateTo, or today if that is later), and a start before today is refused (ERR_INVALID_ACTIVE_FROM_DATE). Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `correctionType` (string): Price correction method
- `correctionValue` (string): Correction value (positive number with max 2 decimals)
- `dateFrom` (string): Schedule start date (YYYY-MM-DD format)
- `dateTo` (string): Schedule end date (YYYY-MM-DD format)
- `description` (string): Schedule description
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `priceCorrection` (string): Price correction direction
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `scheduleId` (number, required): Schedule identifier
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_delete_schedule` (~132 tokens)

[Merchant] Delete a price schedule. This action cannot be undone. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `scheduleId` (number, required): Schedule identifier
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_register_audio` (~213 tokens)

[Merchant] Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Register an audio file (soundbite) for a product to enable audio-based payment initiation.

\**Supported formats:** MP3, WAV, OGG, M4A, FLAC, AAC, WMA, MP4, MOV, up to 100 MB, holding 2 to 120 seconds of audio
\**Note:** For video files, only the audio channel is registered

Input parameters:

- `audioPath` (string, required): Path to the audio file to upload (e.g., '/path/to/audio.mp3')
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_audios` (~121 tokens)

[Merchant] Get all registered audio files for a product. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_get_audio` (~130 tokens)

[Merchant] Get detailed information about a specific audio file. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `audioId` (number, required): Audio identifier
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_update_audio` (~185 tokens)

[Merchant] Update audio information (title) or reassign audio to another product. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `audioId` (number, required): Audio identifier
- `newProductId` (string): Product to move the audio to (starts with 'pr'). Sent as a transfer, which keeps the fingerprint; the target must be in the same shop
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Current product identifier (starts with 'pr')
- `title` (string): New audio title
- `useSandbox` (boolean): Use sandbox environment

### `payware_products_delete_audio` (~135 tokens)

[Merchant] Delete an audio file from a product. This action cannot be undone. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

Input parameters:

- `audioId` (number, required): Audio identifier
- `partnerId` (string): Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)
- `privateKey` (string): RSA private key for authentication (uses environment-specific private key as default)
- `productId` (string, required): Product identifier (starts with 'pr')
- `useSandbox` (boolean): Use sandbox environment

### `payware_logs_query` (~294 tokens)

[Merchant] Query application logs with filters. Premium plan required. Returns paginated JSON log entries for debugging and monitoring your integration.

Input parameters:

- `cursor` (string): Pagination cursor from previous response for fetching next page.
- `from` (string): Start timestamp in ISO 8601 format (e.g., '2024-01-15T00:00:00Z'). Defaults to 24 hours ago.
- `level` (string): Filter by log level, an exact match: WARN returns WARN lines only, not ERROR as well (LogAccessService compares the level for equality).
- `limit` (number): Maximum records to return (default 1000, max 10000).
- `logger` (string): Filter by logger name (partial match). E.g., 'TransactionController' to see transaction-related logs.
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.
- `search` (string): Search text in log messages. Case-insensitive partial match.
- `to` (string): End timestamp in ISO 8601 format (e.g., '2024-01-15T23:59:59Z'). Defaults to now.
- `useSandbox` (boolean): Read the sandbox logs (default) or production's

### `payware_logs_status` (~101 tokens)

[Merchant] Get log availability and storage information. Premium plan required. Shows if logs are available, total size, and file count.

Input parameters:

- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.
- `useSandbox` (boolean): Read the sandbox logs (default) or production's

### `payware_logs_download_url` (~177 tokens)

[Merchant] Get download URL for logs archive. Premium plan required. Returns URL for downloading logs as gzipped JSON file.

Input parameters:

- `from` (string): Start timestamp in ISO 8601 format (e.g., '2024-01-15T00:00:00Z'). Defaults to 24 hours ago.
- `partnerId` (string): Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for authentication. Uses environment-specific private key as default.
- `to` (string): End timestamp in ISO 8601 format (e.g., '2024-01-15T23:59:59Z'). Defaults to now.
- `useSandbox` (boolean): Read the sandbox logs (default) or production's

### `payware_poi_create` (~492 tokens)

[Merchant] Create a single POI (Point of Interaction) - a physical payment point a payer scans.

\**Endpoint:** POST /poi -> 201 Created

\**A POI belongs to a shop, and a shop belongs to a merchant.** `shopCode` is required - use
\`payware_shops_list` to find one rather than guessing. Banks do not own POIs; a financial-institution
principal gets 403 on every POI endpoint, not an empty result.

\**`ttlSeconds` is the price-session TTL, not the POI's lifetime.** It bounds how long a price set on
this POI stays claimable before the POI returns to IDLE. Range 60-600 seconds; the server
defaults it to 300.

\**Creating many at once?** Use `payware_poi_create_batch` instead. It creates up to 50 in one
atomic call, which is both faster and safer than a loop over this tool: a loop that fails halfway
leaves a half-built estate with no record of where it stopped.

Input parameters:

- `callbackUrl` (string): HTTPS URL for this POI's callbacks: poi.scanned (with the new transaction id), poi.expired (price not scanned) and the sale's TRANSACTION_FINALIZED (final status, with poiId). Signed by the ISV that…
- `name` (string): Human-readable POI name, e.g. "Till 3" or "Gate B". Shown in the portal and in POI listings.
- `partnerId` (string): Partner ID from the payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for JWT signing. Uses the environment-specific key as default.
- `shopCode` (string, required): Code of the shop this POI belongs to. Required. Find one with payware_shops_list.
- `ttlSeconds` (integer): Price-session TTL in seconds - how long a price set on this POI stays claimable before it returns to IDLE. Server default 300.
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_create_batch` (~578 tokens)

[Merchant] Create up to 50 POIs in a single **atomic** call - the tool for rolling out a terminal estate.

\**Endpoint:** POST /poi/batch -> 201 Created, returning `{ created, pois: [...] }`

\**Atomic means all or nothing.** Either every entry is created or none is. That is the reason to
prefer this over a loop of `payware_poi_create`: a loop that fails on entry 27 leaves 26 POIs behind
with nothing recording where it stopped, and re-running it duplicates them.

\**A POI belongs to a shop, and a shop belongs to a merchant.** `shopCode` is required - use
\`payware_shops_list` to find one rather than guessing. Banks do not own POIs; a financial-institution
principal gets 403 on every POI endpoint, not an empty result.

\**`ttlSeconds` is the price-session TTL, not the POI's lifetime.** It bounds how long a price set on
this POI stays claimable before the POI returns to IDLE. Range 60-600 seconds; the server
defaults it to 300.

\**Defaults and overrides.** `shopCode`, `ttlSeconds` and `callbackUrl` at the top level apply to
every entry. An entry may override `name`, `ttlSeconds` and `callbackUrl` for itself. `shopCode` is
top-level only - one batch builds one shop.

\**Limits:** 1 to 50 entries. An empty list is `ERR_BATCH_EMPTY`; more than 50 is
\`ERR_BATCH_TOO_LARGE`. Both are refused locally before the request is sent. For a larger rollout,
split it into batches of 50 - each batch is atomic on its own, so record which batches succeeded.

Input parameters:

- `callbackUrl` (string): Default HTTPS callback URL for every POI in the batch.
- `partnerId` (string): Partner ID from the payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `pois` (array, required): The POIs to create. Each entry may set name, ttlSeconds and callbackUrl; anything omitted falls back to the top-level value. An entry may be an empty object, which creates an unnamed POI with the bat…
- `privateKey` (string): RSA private key for JWT signing. Uses the environment-specific key as default.
- `shopCode` (string, required): Code of the shop every POI in this batch belongs to. Required, top-level only. Find one with payware_shops_list.
- `ttlSeconds` (integer): Default price-session TTL for every POI in the batch. Server default 300.
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_list` (~127 tokens)

[Merchant] List all POIs (Points of Interaction) for a merchant.

\**Authentication:** your own JWT (an ISV makes the same call on your behalf).
\**Endpoint:** GET /poi
\**Use Case:** Retrieve all physical payment points configured for a merchant.

POI states: IDLE (no price, no sale running), READY (price set, waiting for a scan), BUSY (scanned, sale running). A disabled POI is not a state: it shows isActive false.

Input parameters:

- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_get` (~122 tokens)

[Merchant] Get details of a specific POI (Point of Interaction).

\**Authentication:** your own JWT (an ISV makes the same call on your behalf).
\**Endpoint:** GET /poi/{poiId}
\**Use Case:** Retrieve full details of a physical payment point including configuration and current state.

\**Required:** POI ID.

Input parameters:

- `poiId` (string, required): The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_get_status` (~378 tokens)

[Merchant] Get the current status of a POI and the outcome of its sales.

\**Authentication:** your own JWT (an ISV makes the same call on your behalf).
\**Endpoint:** GET /poi/{poiId}/status[?sessionToken=...]
\**Use Case:** Follow a sale to its outcome - the backup to callbacks, and on Basic (no transaction
endpoints) the only way when a callback is lost or there is no backend.

\**POI States:**
\- IDLE: no pending price and no sale running
\- READY: price set, waiting for a scan (wins over BUSY: the POI can take the next price while a sale runs)
\- BUSY: a customer scanned and the sale is running

\**Every response** carries lastTransactionId / lastTransactionStatus - the POI's most recent sale, running
(ACTIVE) or finished (CONFIRMED, DECLINED, FAILED, CANCELLED, EXPIRED). Once the POI is back to IDLE,
lastTransactionStatus is how the last sale ended.

\**With sessionToken** (from payware_poi_set_price) the response also carries transactionId /
transactionStatus for exactly that sale - use it when the POI may be re-armed before the previous sale
finishes. Poll every 2-3 seconds and stop at a final status; the read is rate limited.

\**Required:** POI ID.

Input parameters:

- `poiId` (string, required): The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)
- `sessionToken` (string): Optional. The sessionToken returned by payware_poi_set_price; returns that sale's transaction and status
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_set_price` (~476 tokens)

[Merchant] Set a pending price on a POI for customer payment.

\**Authentication:** your own JWT (an ISV makes the same call on your behalf).
\**Endpoint:** PUT /poi/{poiId}/price
\**Use Case:** Set the amount a customer should pay when they scan the POI.

The POI moves to READY and waits for a scan until the TTL expires. The scan creates the transaction and
the POI is BUSY until the sale is final.

\**Only amount, currency, ttlSeconds and tip are accepted.** There is no description, callback URL or passback
field on a price - the callback URL is set on the POI when it is created, and a POI without one sends no
callbacks.

\**Tip (optional):** the merchant's tip, INSIDE amount (amount = bill + tip), e.g. a waiter's tip on a table's
QR or NFC tag. The payment created at the scan records it as the merchant's tip, and the payer's bank offers no
second one. Leave it out to let the payer add a tip in the bank app, where the shop allows tips.

\**Keep the returned sessionToken** until the sale has a final status: pass it to
payware_poi_get_status to read that sale's transaction and outcome.

\**Required:** POI ID, amount, currency.

Input parameters:

- `amount` (string, required): Payment amount (e.g., '25.50'), positive and no finer than the currency's smallest unit
- `currency` (string, required): ISO 4217 currency code (e.g., 'EUR', 'USD', 'GBP')
- `poiId` (string, required): The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)
- `tip` (string): Optional merchant tip, included in amount (e.g. amount '22.00' with tip '2.00' for a 20.00 bill). Above 0, at the currency's scale, at most the amount before it.
- `ttlSeconds` (integer): Seconds until the price expires if nobody scans it (60-600). Defaults to the POI's own ttlSeconds.
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_cancel_price` (~230 tokens)

[Merchant] Cancel a pending price on a POI, resetting it to IDLE state.

\**Authentication:** your own JWT (an ISV makes the same call on your behalf).
\**Endpoint:** DELETE /poi/{poiId}/price
\**Use Case:** Cancel a price that was set but not yet scanned (e.g., order cancelled).

The POI returns to IDLE and is ready for a new price.

\**Only before the scan.** The scan is the customer's bank processing the payment, so from then on a POI
sale cannot be cancelled by the merchant or an ISV, on any plan: this answers 409
ERR_POI_NO_PENDING_PAYMENT, and cancelling the transaction itself answers 409 ERR_ALREADY_PROCESSED. The
sale completes or expires; the POI accepts the next price meanwhile.

\**Required:** POI ID.

Input parameters:

- `poiId` (string, required): The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_poi_get_qrcode` (~155 tokens)

[Merchant] Generate a QR code image for a POI that customers can scan.

\**Endpoint:** GET /poi/{poiId}/image
\**Authentication:** your own JWT
\**Use Case:** Generate QR codes for printing or displaying on screens.

\**Formats:** PNG (default), SVG, JPG

Returns the image itself (MCP image content); an SVG comes back as its markup.

\**Required:** POI ID.

Input parameters:

- `format` (string): Image format (default: PNG)
- `poiId` (string, required): The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_shops_list` (~405 tokens)

[Merchant] List the merchant outlets (shops) the caller can act on.

\**Endpoint:** GET /shops

\**Use this before any call that takes a `shop` / `shopCode`.** Creating a transaction, creating a
product, creating a POI and batching POIs all take one, and an invalid code is a 400
(`ERR_INVALID_SHOP_CODE`). Omitting it falls back to the merchant's default shop, which is a
reasonable guess for a single-outlet merchant and the wrong outlet for everyone else - the sale lands
against the wrong shop, and nothing about the response says so.

\**Returned per shop** (server ShopDTO): `code` (the value to pass as `shop` / `shopCode`), `name`,
\`isDefault`, `ecommerce`, `country`, `tipsAllowed` and the shop's label, image and terms URLs.
\`tipsAllowed: true` means the payer's bank may add a tip to this shop's payments, with or without lines: the payer
pays the amount plus the tip, and payware records it on the payment as `tip` (never a line), in the callback and
the history. Without it the payer pays exactly the amount. The merchant switches it in the portal's shop form; it is
off by default. A merchant's own tip (`tip` on create) needs no such setting.

⚠️ **Requires Standard or Premium.** A Basic merchant gets **403**.

\**Note on financial institutions:** banks do not own shops. A bank principal calling this gets 403,
not an empty list.

Input parameters:

- `partnerId` (string): Partner ID from the payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
- `privateKey` (string): RSA private key for JWT signing. Uses the environment-specific key as default.
- `useSandbox` (boolean): Use sandbox environment for testing

### `payware_campaigns_list_campaigns` (~125 tokens)

[Merchant] List the merchant's campaigns. A campaign groups placements, possibly of different products, and reports their combined results.

\**Endpoint:** GET /campaigns

Changing anything here needs the PRM plan, and below it a change answers 403 ERR_UNAUTHORIZED_OPERATION; reading works on every plan, results only on PRM. A merchant that leaves PRM keeps its placements read-only, and a printed placement code then pays as its plain product with no attribution.

Input parameters:

- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_campaigns_create_campaign` (~149 tokens)

[Merchant] Create a campaign. Attach placements to it by giving its campaignId when you create or replace a placement.

\**Endpoint:** POST /campaigns (PRM plan)

Input parameters:

- `endsOn` (string): Last day, YYYY-MM-DD
- `externalRef` (string): An agency's own campaign code, up to 100 characters
- `name` (string, required): Campaign name, up to 100 characters
- `startsOn` (string): First day, YYYY-MM-DD
- `status` (string): Descriptive only: it does not switch the placements on or off
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_campaigns_get_campaign` (~90 tokens)

[Merchant] Get a campaign, with the IDs of its placements you can see.

\**Endpoint:** GET /campaigns/{campaignId}

Input parameters:

- `campaignId` (string, required): The campaign's ID: cp + 8 letters or digits, e.g. cp7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_campaigns_update_campaign` (~206 tokens)

[Merchant] **Replace** a campaign's details. An omitted startsOn, endsOn or externalRef is cleared; an omitted status keeps the current one. Get the campaign first and send every value you want to keep.

\**Endpoint:** PUT /campaigns/{campaignId} (PRM plan)

Input parameters:

- `campaignId` (string, required): The campaign's ID: cp + 8 letters or digits, e.g. cp7e4rCToG
- `endsOn` (string): Last day, YYYY-MM-DD
- `externalRef` (string): An agency's own campaign code, up to 100 characters
- `name` (string, required): Campaign name, up to 100 characters
- `startsOn` (string): First day, YYYY-MM-DD
- `status` (string): Descriptive only: it does not switch the placements on or off
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_campaigns_delete_campaign` (~97 tokens)

[Merchant] Delete a campaign. Its placements stay, detached from it, and keep working.

\**Endpoint:** DELETE /campaigns/{campaignId} (PRM plan)

Input parameters:

- `campaignId` (string, required): The campaign's ID: cp + 8 letters or digits, e.g. cp7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_campaigns_get_campaign_stats` (~231 tokens)

[Merchant] A campaign's results over [from, to): offers shown when a bank resolved one of its placement IDs (resolutions), offers shown after a recognised soundbite tap (recognitions), payments started (transactions) and confirmed, and confirmed amounts by currency.

\**Endpoint:** GET /campaigns/{campaignId}/stats (PRM plan)

Input parameters:

- `campaignId` (string, required): The campaign's ID: cp + 8 letters or digits, e.g. cp7e4rCToG
- `from` (string): Start of the period: a date (YYYY-MM-DD, the start of that day in UTC) or an ISO-8601 instant with an offset, e.g. 2026-10-19T00:00:00+03:00. Default: 30 days before to
- `to` (string): End of the period, exclusive, in the same forms. Default: now. Any length: impressions are kept for good
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_list_placements` (~277 tokens)

[Merchant] List a product's placements. A placement is one way the product is distributed - a poster, a TV spot, a packaging label - with its own ID (pl + 8 characters), so every payment it starts is attributed to it. One page at a time, newest first: a product has no limit on its placements, and the response is { content, number, size, totalElements, totalPages }, so ask for the next page while number + 1 < totalPages.

\**Endpoint:** GET /products/{productId}/placements

Changing anything here needs the PRM plan, and below it a change answers 403 ERR_UNAUTHORIZED_OPERATION; reading works on every plan, results only on PRM. A merchant that leaves PRM keeps its placements read-only, and a printed placement code then pays as its plain product with no attribution.

Input parameters:

- `page` (integer): The page, counted from 0. Default: 0
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `size` (integer): Placements per page, 1 to 100. Default: 50
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_create_placement` (~463 tokens)

[Merchant] Create a placement for a product; a product has no limit on its placements. The response carries its placementId, which goes on the medium wherever the product ID would: a QR code (its payware link, or payware:{placementId}), an NFC tag, a BLE beacon, a link, a barcode or an SMS. A bank resolving it pays for the product, and the payment is attributed to the placement. For a SOUNDBITE carrier, add airing rules so taps during the airing are attributed.

\**Endpoint:** POST /products/{productId}/placements (PRM plan)

Input parameters:

- `active` (boolean): Whether it is in use. Governs airing and soundbite attribution; a printed code keeps resolving until the placement is deleted
- `activeFrom` (string): Start of its active window, ISO-8601 with an offset. Empty means the product's
- `activeTo` (string): End of its active window, ISO-8601 with an offset. Empty means the product's
- `campaignId` (string): The campaign it belongs to, if any (cp + 8 characters)
- `carriers` (array, required): The methods that carry the placement ID to a payer. SOUNDBITE airs the product's audio and needs airing rules
- `channel` (string): Descriptive, e.g. the TV channel or the website, up to 100 characters
- `externalRef` (string): An agency's own code, up to 100 characters
- `location` (string): Descriptive, e.g. the venue or the address, up to 255 characters
- `medium` (string, required): What the placement is
- `name` (string, required): Placement name, up to 100 characters, e.g. "Sofia metro posters, October"
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `regions` (array): ISO 3166-1 alpha-2 codes of the countries it airs in, matched against the paying bank's country. Empty means anywhere
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_placement` (~116 tokens)

[Merchant] Get a placement.

\**Endpoint:** GET /products/{productId}/placements/{placementId}

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_update_placement` (~461 tokens)

[Merchant] **Replace** a placement's details. Every field is replaced, so an omitted optional field is cleared - an omitted campaignId detaches it from its campaign; an omitted active keeps the current value. Get the placement first and send every value you want to keep. The placement ID does not change, so printed codes keep working.

\**Endpoint:** PUT /products/{productId}/placements/{placementId} (PRM plan)

Input parameters:

- `active` (boolean): Whether it is in use. Governs airing and soundbite attribution; a printed code keeps resolving until the placement is deleted
- `activeFrom` (string): Start of its active window, ISO-8601 with an offset. Empty means the product's
- `activeTo` (string): End of its active window, ISO-8601 with an offset. Empty means the product's
- `campaignId` (string): The campaign it belongs to, if any (cp + 8 characters)
- `carriers` (array, required): The methods that carry the placement ID to a payer. SOUNDBITE airs the product's audio and needs airing rules
- `channel` (string): Descriptive, e.g. the TV channel or the website, up to 100 characters
- `externalRef` (string): An agency's own code, up to 100 characters
- `location` (string): Descriptive, e.g. the venue or the address, up to 255 characters
- `medium` (string, required): What the placement is
- `name` (string, required): Placement name, up to 100 characters, e.g. "Sofia metro posters, October"
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `regions` (array): ISO 3166-1 alpha-2 codes of the countries it airs in, matched against the paying bank's country. Empty means anywhere
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_delete_placement` (~158 tokens)

[Merchant] Delete a placement. **Its printed codes and its payware link stop resolving**, and its ID is never reused. To stop airing and attribution but keep printed codes working, replace it with active false instead.

\**Endpoint:** DELETE /products/{productId}/placements/{placementId} (PRM plan)

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_placement_image` (~201 tokens)

[Merchant] A placement's QR code (carrying the placement's payware link, https://go.payware.eu/{placementId}, which needs no API call) or Code 128 barcode (carrying the plain ID), for print. PNG and JPG come back as an image, SVG as its markup.

\**Endpoint:** GET /products/{productId}/placements/{placementId}/image

Input parameters:

- `format` (string): Image format. Default PNG
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `type` (string): QR code or barcode. Default QR
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_placement_stats` (~264 tokens)

[Merchant] A placement's results over [from, to): offers shown when a bank resolved its ID (resolutions), offers shown after a recognised soundbite tap (recognitions), payments started (transactions) and confirmed, and confirmed amounts by currency.

\**Endpoint:** GET /products/{productId}/placements/{placementId}/stats (PRM plan)

Input parameters:

- `from` (string): Start of the period: a date (YYYY-MM-DD, the start of that day in UTC) or an ISO-8601 instant with an offset, e.g. 2026-10-19T00:00:00+03:00. Default: 30 days before to
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `to` (string): End of the period, exclusive, in the same forms. Default: now. Any length: impressions are kept for good
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_list_airings` (~151 tokens)

[Merchant] List a placement's airing rules. A rule is a recurrence with time windows, in an IANA time zone; a soundbite tap during an airing is attributed to the placement.

\**Endpoint:** GET /products/{productId}/placements/{placementId}/airings

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_create_airing` (~463 tokens)

[Merchant] Add an airing rule to a placement: up to 100 rules per placement. Example: "daily 08:00-08:30 and 15:40-16:10" is one DAILY rule with two windows. Check `warnings` in the response: AIRING_OVERLAP means another soundbite placement of the same product airs at the same time in an overlapping region, and a tap then is attributed to neither.

\**Endpoint:** POST /products/{productId}/placements/{placementId}/airings (PRM plan)

Input parameters:

- `daysOfWeek` (array): WEEKLY: the days it airs on
- `endDate` (string): Last day, YYYY-MM-DD, at most 366 days after startDate. Omit for open-ended
- `excludedDates` (array): Days it does not air, YYYY-MM-DD
- `expectedAudience` (integer): Expected audience per airing, for your own planning
- `frequency` (string, required): How the rule repeats
- `monthDays` (array): MONTHLY by date: days of the month. A day a month lacks is skipped
- `monthWeek` (integer): MONTHLY by weekday: which week, -1 for the last. Use with monthWeekday
- `monthWeekday` (string): MONTHLY by weekday: the weekday
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `repeatEvery` (integer): Every N days, weeks or months. Default 1
- `startDate` (string, required): First day, YYYY-MM-DD, in the rule's time zone
- `timeZone` (string): IANA time zone, e.g. Europe/Sofia. Default: the product's
- `useSandbox` (boolean): Use the sandbox (the default) rather than production
- `windows` (array, required): Time windows on each day it airs, local to the time zone: 1 to 24, each up to 6 hours

### `payware_products_replace_airings` (~194 tokens)

[Merchant] **Replace all** of a placement's airing rules with this list, all or nothing: when any rule is refused, nothing is saved and each refused rule is listed by its index. An empty list removes every rule. Suited to loading an agency's schedule in one call.

\**Endpoint:** PUT /products/{productId}/placements/{placementId}/airings (PRM plan)

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `rules` (array, required): The complete new set of airing rules, up to 100
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_next_airings` (~173 tokens)

[Merchant] A placement's next airings, each in its rule's time zone so daylight-saving shifts are visible. Use it to check a rule does what was meant before relying on it.

\**Endpoint:** GET /products/{productId}/placements/{placementId}/airings/next

Input parameters:

- `count` (integer): How many, 1 to 100. Default 10
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_airing` (~144 tokens)

[Merchant] Get one airing rule.

\**Endpoint:** GET /products/{productId}/placements/{placementId}/airings/{ruleId}

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `ruleId` (integer, required): The airing rule's ID, from payware_products_list_airings
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_update_airing` (~433 tokens)

[Merchant] **Replace** one airing rule: every field is replaced, so send the whole rule. Check `warnings` in the response for AIRING_OVERLAP.

\**Endpoint:** PUT /products/{productId}/placements/{placementId}/airings/{ruleId} (PRM plan)

Input parameters:

- `daysOfWeek` (array): WEEKLY: the days it airs on
- `endDate` (string): Last day, YYYY-MM-DD, at most 366 days after startDate. Omit for open-ended
- `excludedDates` (array): Days it does not air, YYYY-MM-DD
- `expectedAudience` (integer): Expected audience per airing, for your own planning
- `frequency` (string, required): How the rule repeats
- `monthDays` (array): MONTHLY by date: days of the month. A day a month lacks is skipped
- `monthWeek` (integer): MONTHLY by weekday: which week, -1 for the last. Use with monthWeekday
- `monthWeekday` (string): MONTHLY by weekday: the weekday
- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `repeatEvery` (integer): Every N days, weeks or months. Default 1
- `ruleId` (integer, required): The airing rule's ID, from payware_products_list_airings
- `startDate` (string, required): First day, YYYY-MM-DD, in the rule's time zone
- `timeZone` (string): IANA time zone, e.g. Europe/Sofia. Default: the product's
- `useSandbox` (boolean): Use the sandbox (the default) rather than production
- `windows` (array, required): Time windows on each day it airs, local to the time zone: 1 to 24, each up to 6 hours

### `payware_products_delete_airing` (~149 tokens)

[Merchant] Delete one airing rule.

\**Endpoint:** DELETE /products/{productId}/placements/{placementId}/airings/{ruleId} (PRM plan)

Input parameters:

- `placementId` (string, required): The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `ruleId` (integer, required): The airing rule's ID, from payware_products_list_airings
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_airing_calendar` (~171 tokens)

[Merchant] Every airing of the merchant's placements between from and to, across all products, ordered by start time and each in its rule's time zone. Answers "what is on air this week" in one call. The range may span at most 400 days.

\**Endpoint:** GET /placements/calendar

Input parameters:

- `from` (string, required): Start of the range: a date (YYYY-MM-DD, the start of that day in UTC) or an ISO-8601 instant with an offset, e.g. 2026-10-19T00:00:00+03:00
- `to` (string, required): End of the range, after from, in the same forms
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_shops_get_delivery` (~260 tokens)

[Merchant] Read what a shop charges for delivery, per country.

\**Endpoint:** GET /shops/{shopCode}/delivery

\**Warn the merchant** when the answer lists `undeliverableProducts` (`productId`, `name`, `currency`): shippable products the table has no prices for in their currency, so they cannot be delivered anywhere.

Answers `{"shopCode":"S1","countries":[{"country":"BG","currency":"EUR","fee":"5.00","freeAbove":"50.00"}]}`. `freeAbove` is optional. **An empty list means "deliver anywhere, no fee"**, which is also what a shop with no table has. With a table, only the listed countries are served and a payer or an agent buying from elsewhere gets 409 `ERR_DELIVERY_COUNTRY_NOT_SERVED`.

Needs a plan that can ship: Standard or Premium. A Basic (BSC) merchant is refused with 403 `ERR_METHOD_NOT_ALLOWED_FOR_CURRENT_USER_PLAN`. Changes are audit-logged.

Input parameters:

- `shopCode` (string, required): The shop code, from payware_shops_list
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_shops_set_delivery` (~398 tokens)

[Merchant] **Replace** a shop's whole delivery table. Whatever you do not send is removed, so read it first with `payware_shops_get_delivery` and send every row you want to keep. An empty `countries` list means "deliver anywhere, no fee".

\**Endpoint:** PUT /shops/{shopCode}/delivery

Each row: `country` (ISO alpha-2), `currency`, `fee` and optionally `freeAbove`, all amounts decimal strings at the currency's payable scale (at most 15 significant and 15 integer digits). Rules: no two rows with the same country and currency, at most 250 rows, `fee` 0 or more, `freeAbove` above zero. A refusal is 400 `ERR_INVALID_DELIVERY_COUNTRY`, `ERR_INVALID_DELIVERY_SETTINGS` or `ERR_INVALID_AMOUNT_LENGTH` and nothing is saved.

\**Read the answer.** It is the saved table and, when the table is not empty, `undeliverableProducts` (also on every read of the table, until resolved) (`productId`, `name`, `currency`): the shop's active shippable products whose currency has no row in it, so they can now be delivered nowhere. It is absent when there are none. The table is saved either way: tell the merchant, and add rows in those currencies if that was not the intent.

Needs a plan that can ship: Standard or Premium. A Basic (BSC) merchant is refused with 403 `ERR_METHOD_NOT_ALLOWED_FOR_CURRENT_USER_PLAN`. Changes are audit-logged.

Input parameters:

- `countries` (array, required): The complete table: one row per country and currency. Empty means deliver anywhere with no fee
- `shopCode` (string, required): The shop code, from payware_shops_list
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_get_delivery` (~316 tokens)

[Merchant] Read a product's delivery overrides: the countries it is not delivered to and the countries where it costs extra.

\**Endpoint:** GET /products/{productId}/delivery

\**Warn the merchant** when the answer carries `noDeliveryInCurrency: true`: the product is shippable, its shop has a delivery table, and none of it is in the product's currency, so it cannot be delivered anywhere until prices in that currency are added to the shop.

Answers `{"productId":"pr...","countries":[{"country":"RO","excluded":true},{"country":"BG","excluded":false,"surchargePerUnit":"3.00"}]}`. The surcharge is in the product's currency (so the product's currency cannot change while it has one: `ERR_PRODUCT_CURRENCY_HAS_SURCHARGES`). Any surcharge makes a `quantity` required when an institution processes the product (`ERR_QUANTITY_REQUIRED`). The overrides only narrow the shop's table: a surcharge on a country the shop does not list has no effect until the shop serves it.

Needs a plan that can ship: Standard or Premium. A Basic (BSC) merchant is refused with 403 `ERR_METHOD_NOT_ALLOWED_FOR_CURRENT_USER_PLAN`. Changes are audit-logged.

Input parameters:

- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

### `payware_products_set_delivery` (~255 tokens)

[Merchant] **Replace** a product's delivery overrides. Whatever you do not send is removed, so read them first with `payware_products_get_delivery`.

\**Endpoint:** PUT /products/{productId}/delivery

Each row is either `{"country":"RO","excluded":true}` (not delivered there; no surcharge) or `{"country":"BG","excluded":false,"surchargePerUnit":"3.00"}` (delivered, with an extra amount per unit in the product's currency). The product is useful here when it is shippable. Unknown product or one outside an ISV's shops: 404 `ERR_MISSING_PRODUCT`.

Needs a plan that can ship: Standard or Premium. A Basic (BSC) merchant is refused with 403 `ERR_METHOD_NOT_ALLOWED_FOR_CURRENT_USER_PLAN`. Changes are audit-logged.

Input parameters:

- `countries` (array, required): The complete list of overrides, one row per country. Empty clears them
- `productId` (string, required): The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
- `useSandbox` (boolean): Use the sandbox (the default) rather than production

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server#diagnostics

## Score history

- 2026-11-22: 77
- 2026-11-21: 81
- 2026-11-20: 80
- 2026-11-19: 80
- 2026-11-18: 65
- 2026-11-17: 80
- 2026-11-16: 80
- 2026-11-15: 65
- 2026-11-14: 80
- 2026-11-13: 69
- 2026-11-12: 79
- 2026-11-11: 65
- 2026-11-10: 65
- 2026-11-09: 80
- 2026-11-08: 80
- 2026-11-07: 65
- 2026-11-06: 80
- 2026-11-05: 79
- 2026-11-04: 79
- 2026-11-03: 79
- 2026-11-02: 80
- 2026-11-01: 80
- 2026-10-31: 80
- 2026-10-30: 80
- 2026-10-29: 80
- 2026-10-28: 80
- 2026-10-27: 80
- 2026-10-26: 80
- 2026-10-25: 80
- 2026-10-24: 80

## Common questions

### What is the payware MCP server?

payware is an MCP server listed in the public MCP registry as io.github.payware/mcp-server. payware A2A payments API for merchants, ISVs, payment institutions and buying agents. This page covers its npm package (@payware/mcp-server).

### Is the payware MCP server safe to use?

payware scores 77 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 22 November 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the payware MCP server expose?

payware exposes 79 tools: payware_authentication_generate_rsa_keys, payware_authentication_create_jwt_token, payware_authentication_validate_jwt, payware_authentication_test_jwt, payware_authentication_setup_sandbox_auth, and 74 more. Their descriptions and schemas cost roughly 23,424 tokens of context every time the server is loaded.

### Is the payware MCP server still maintained?

payware is still listed as active in the MCP registry. We last reached this channel on 22 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the payware MCP server under?

payware declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the payware MCP server?

VerifyMCP ran 15 checks on payware, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about payware: Malware scan. Endpoint Security and Transport & Reachability do not apply to an npm package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- npm package: https://www.npmjs.com/package/@payware/mcp-server
- Socket report: https://socket.dev/npm/package/@payware/mcp-server
- Repository: https://github.com/payware/mcp-server
- Website: https://payware.eu/en/for-developers
- Changelog RSS feed: https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/payware-mcp-server/payware-mcp-server
