All servers / Payments / Payware MCP server
Payware MCP server
Official MCP server for payware payment API integration
Tested by ConnectATDScore 90 out of 100. Tested 2026-11-19 on package version 2.4.0. Package: @payware/mcp-server Β· source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 20 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (2.9 seconds including download)
- Tools offered: 79
- Last published: 2026-11-17
- Weekly downloads (npm): 1,078
- License: MIT Β· Direct dependencies: 6
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
payware_authentication_generate_rsa_keys1 of 1 parameter described[Merchant] Generate RSA key pair for payware API authentication
payware_authentication_create_jwt_token4 of 4 parameters described[Merchant] Create JWT token for payware API authentication according to official documentation
payware_authentication_validate_jwt2 of 2 parameters described[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
payware_authentication_test_jwt4 of 4 parameters described[Merchant] Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, SHA-256 hash calculation, and final JWT structure
payware_authentication_setup_sandbox_auth2 of 2 parameters described[Merchant] Setup sandbox authentication configuration for payware API
payware_generate_code_example5 of 5 parameters described[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.
payware_generate_documentation2 of 2 parameters described[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.
payware_utils_format_request5 of 5 parameters described[Merchant] Format and validate payware API requests with proper structure and headers
payware_utils_server_info1 of 1 parameter described[Merchant] Get MCP server version, status, and environment information
payware_utils_format_json_deterministic4 of 4 parameters described[Merchant] Format JSON payload with deterministic key sorting for consistent SHA-256 calculation and payware API compliance
payware_operations_create_transaction31 of 31 parameters described[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` line in your `items` is 400 `ERR_INVALID_ITEMS`. payware records the tip on the payment and returns it as `tip` beside `items` and `total`, which stay what was sold: the payer paid `total` + `tip`, and the payware fee applies to the whole of it. The response, the callback and the transaction history carry `items`, `total` and `tip` back. Lines change nothing about who is paid. π **TIP** (`tip`, sent as `trData.tip`, optional): one tip per payment, recorded on it and never a line. - **Yours**, for a till that asks the payer before it shows the code: `amount` is what the payer pays, tip included, and `tip` is the part that is the tip, above 0 and at most the amount before it (400 `ERR_INVALID_TIP`). `items`, if any, add up to `amount` minus `tip`. The payer's bank shows it, pays exactly `amount` and offers no second tip. No shop setting is needed. - **The payer's**, without yours: where your shop allows tips (`tipsAllowed`, the portal's shop form), the payer may add a tip in their bank, and pays the amount plus the tip. Elsewhere the payer pays exactly the amount: there is no paying more without a tip. - Either way it comes back as `tip` in the response, the callback and the transaction history, and the payware fee applies to the whole amount. β±οΈ **PAYMENT LIFETIME** (`timeToLive`, sent as `trOptions.timeToLive`, 120 seconds when left out): payware accepts 60 seconds up to the merchant's own ceiling, which is 600 by default and which the merchant can raise in the portal (Settings > Authentication, Longest payment lifetime) up to 2,592,000 (30 days). Above the ceiling the server answers 400 `ERR_INVALID_TTL`. This tool checks 60 to 2,592,000 before sending; only payware knows the ceiling. An ISV acting for a merchant gets that merchant's ceiling and cannot change it. The e-commerce plugins keep 60-600, because their buyer is waiting at the checkout. β³ **DEFERRED MERCHANT LEG** (optional, `trOptions.deferredAllowed`) By default the payer's institution pays this transaβ¦
payware_operations_get_transaction_status4 of 4 parameters described[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" } } ``` Three things about that object: - **`imageDigest` is an obligation, not decoration.** It is the SHA-256 payware pinned for the image at `imageUrl`. Fetch the image, verify its bytes against this digest before rendering it to a payer, and fall back to a neutral placeholder on mismatch. Present only when `imageUrl` is the product's own image. - **`regularPrice` is display-only, and appears only when there is a genuine saving** - i.e. when it is higher than the transaction `amount`. The top-level `amount` and `currency` are authoritative and are what the payer pays; the object does not repeat them. - **Availability follows the merchant's plan.** `imageUrl` and `termsUrl` are Standard and above; `termsText` and the descriptions are universal. A missing field is a plan boundary, not an error. For a `pr`/`ps` product identifier the values are resolved live; for the resulting `pw` transaction they are the snapshot frozen at creation, so the response always reflects what the payer could have been shown at scan time. π° **Amounts follow the currency, not a fixed two decimals.** `amount`, `fee`, `payerAmount` and `payeeAmount` are decimal strings at the smallest unit their own currency can be paid in - none for JPY, two for EUR, eight for BTC. Parse them with a decimal type; never compare them as strings, and never assume two places. `feeRate` carries up to six decimals and `feeFixed` full stored precision: both are informational, and recomputing the fee from them and submitting that at finalize is rejected with ERR_FEE_MISMATCH. Echo `fee` back unchanged instead.
payware_operations_cancel_transaction5 of 5 parameters described[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.
payware_operations_get_transaction_history4 of 4 parameters described[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.retryable` and `error.retryAfterSeconds`.
payware_operations_process_transaction15 of 15 parameters described[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 } } ```
payware_operations_simulate_callback18 of 18 parameters described[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, sent when you created the payment, or the payer's, added in their bank where your shop allows tips; the payer paid `total` + `tip` and the fee applies to the whole of it. On CONFIRMED `amount` is net of the fee, so **`amount` + `fee` = `total` + `tip`**; on any other status nothing was paid and `amount` equals `total` + `tip`. Give `items` (and `tip`) and leave `amount` out: the tool works it out, and refuses an `amount` the server would never send with those lines. **Not on this payload:** `deliveryAddress` (removed 2026-08-07 - fetch it from `payware_operations_get_transaction_history`, which is authenticated and tenant-scoped), `producerPartnerId`, `transactionType` and `initiatedBy` (the last two are carried on TRANSACTION_PROCESSED, which merchants do not receive).
payware_data_list_reports2 of 2 parameters described[Merchant] List all available report types with their configurations, descriptions, and visibility settings. Production only - not supported in sandbox.
payware_data_generate_report9 of 9 parameters described[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.
payware_data_get_report_requests3 of 3 parameters described[Merchant] Get all execution requests for a specific report type. Returns historical execution records with status and parameters. Production only - not supported in sandbox.
payware_data_get_report_status3 of 3 parameters described[Merchant] Get the status of an asynchronous report generation request. Use this to monitor report progress.
payware_data_export_report4 of 4 parameters described[Merchant] Export a READY report in a specific format (PDF, CSV, Excel, JSON). The report must be in READY status first.
payware_data_get_export_list3 of 3 parameters described[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.
payware_data_get_export_status3 of 3 parameters described[Merchant] Get the status of a report export request. Use this to monitor export progress.
payware_data_download_export4 of 4 parameters described[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.
payware_data_cancel_report3 of 3 parameters described[Merchant] Cancel a running report generation. Only reports in QUEUED status can be cancelled.
payware_data_cancel_export3 of 3 parameters described[Merchant] Cancel a running export process. Only exports in QUEUED status can be cancelled.
payware_products_create_product22 of 22 parameters described[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
payware_products_list_products3 of 3 parameters described[Merchant] Get a list of all products for the merchant account
payware_products_get_product4 of 4 parameters described[Merchant] Get detailed information about a specific product by ID
payware_products_update_product23 of 23 parameters described[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).
payware_products_delete_product4 of 4 parameters described[Merchant] Delete a product from the merchant account. This action cannot be undone.
payware_products_get_product_image15 of 15 parameters described[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
payware_products_create_schedule10 of 10 parameters described[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).
payware_products_get_schedules4 of 4 parameters described[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).
payware_products_get_schedule5 of 5 parameters described[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).
payware_products_update_schedule11 of 11 parameters described[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).
payware_products_delete_schedule5 of 5 parameters described[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).
payware_products_register_audio5 of 5 parameters described[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
payware_products_get_audios4 of 4 parameters described[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).
payware_products_get_audio5 of 5 parameters described[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).
payware_products_update_audio7 of 7 parameters described[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).
payware_products_delete_audio5 of 5 parameters described[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).
payware_logs_query10 of 10 parameters described[Merchant] Query application logs with filters. Premium plan required. Returns paginated JSON log entries for debugging and monitoring your integration.
payware_logs_status3 of 3 parameters described[Merchant] Get log availability and storage information. Premium plan required. Shows if logs are available, total size, and file count.
payware_logs_download_url5 of 5 parameters described[Merchant] Get download URL for logs archive. Premium plan required. Returns URL for downloading logs as gzipped JSON file.
payware_poi_create7 of 7 parameters described[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.
payware_poi_create_batch7 of 7 parameters described[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.
payware_poi_list1 of 1 parameter described[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.
payware_poi_get2 of 2 parameters described[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.
payware_poi_get_status3 of 3 parameters described[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.
payware_poi_set_price5 of 5 parameters described[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 and ttlSeconds 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. **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.
payware_poi_cancel_price2 of 2 parameters described[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.
payware_poi_get_qrcode3 of 3 parameters described[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.
payware_shops_list3 of 3 parameters described[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.
payware_campaigns_list_campaigns1 of 1 parameter described[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.
payware_campaigns_create_campaign6 of 6 parameters described[Merchant] Create a campaign. Attach placements to it by giving its campaignId when you create or replace a placement. **Endpoint:** POST /campaigns (PRM plan)
payware_campaigns_get_campaign2 of 2 parameters described[Merchant] Get a campaign, with the IDs of its placements you can see. **Endpoint:** GET /campaigns/{campaignId}
payware_campaigns_update_campaign7 of 7 parameters described[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)
payware_campaigns_delete_campaign2 of 2 parameters described[Merchant] Delete a campaign. Its placements stay, detached from it, and keep working. **Endpoint:** DELETE /campaigns/{campaignId} (PRM plan)
payware_campaigns_get_campaign_stats4 of 4 parameters described[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)
payware_products_list_placements4 of 4 parameters described[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.
payware_products_create_placement13 of 13 parameters described[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)
payware_products_get_placement3 of 3 parameters described[Merchant] Get a placement. **Endpoint:** GET /products/{productId}/placements/{placementId}
payware_products_update_placement14 of 14 parameters described[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)
payware_products_delete_placement3 of 3 parameters described[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)
payware_products_get_placement_image5 of 5 parameters described[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
payware_products_get_placement_stats5 of 5 parameters described[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)
payware_products_list_airings3 of 3 parameters described[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
payware_products_create_airing15 of 15 parameters described[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)
payware_products_replace_airings4 of 4 parameters described[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)
payware_products_get_next_airings4 of 4 parameters described[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
payware_products_get_airing4 of 4 parameters described[Merchant] Get one airing rule. **Endpoint:** GET /products/{productId}/placements/{placementId}/airings/{ruleId}
payware_products_update_airing16 of 16 parameters described[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)
payware_products_delete_airing4 of 4 parameters described[Merchant] Delete one airing rule. **Endpoint:** DELETE /products/{productId}/placements/{placementId}/airings/{ruleId} (PRM plan)
payware_products_get_airing_calendar3 of 3 parameters described[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
payware_shops_get_delivery2 of 2 parameters described[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.
payware_shops_set_delivery3 of 3 parameters described[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.
payware_products_get_delivery2 of 2 parameters described[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.
payware_products_set_delivery3 of 3 parameters described[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.
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.