[Merchant] Generate RSA key pair for payware API authentication

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

[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

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

[Merchant] Setup sandbox authentication configuration for payware API

[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.

[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.

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

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

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

[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

⚙️ TRANSACTION OPTIONS (trOptions object):

• type, timeToLive, 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:

{
  "shop": "...",
  "account": "...",
  "friendlyName": "...",
  "callbackUrl": "...",
  "passbackParams": "...",
  "trData": {
    "amount": "25.50",
    "currency": "EUR", 
    "reasonL1": "...",
    "reasonL2": "..."
  },
  "trOptions": {
    "type": "QR",
    "timeToLive": 300
  },
  "qrOptions": { ... }
}

⏳ DEFERRED MERCHANT LEG (optional, trOptions.deferredAllowed)

By default the payer's institution pays this transaction with an instant or an internal transfer. deferredAllowed: true also lets it use an ordinary credit transfer that settles later. Rules:

• Honoured only on your own call without POS terminal producer fields. With producerPartnerId, terminalId or terminalManufacturer the transaction is refused with 400 ERR_DEFERRED_TRANSFER_NOT_ALLOWED: a till payment stays instant or internal.

• A deferred payment stays ACTIVE, i.e. pending, until the transfer settles, which can take days, and so can stay ACTIVE past its timeToLive. Keep polling or wait for the callback; never treat it as expired yourself. CONFIRMED arrives once the money has reached your account.

• Echoed as deferredAllowed: true in the create response and on status reads when set; absent otherwise. Leave it out for instant or internal only.

🏭 POS TERMINAL PRODUCER ATTRIBUTION (optional, root level)

Only relevant if the transaction originates on a POS terminal whose producer has a revenue-share agreement with payware. Three fields, all optional:

• producerPartnerId - the 8-character partnerId payware issued to the terminal producer. An unrecognised value fails the transaction with a 400 (ERR_INVALID_PRODUCER_ID) - it is deliberately not ignored, so that a terminal configured with the wrong id fails on its first sale where an installer can see it. Omit the field entirely when there is no producer arrangement; never send an empty string.

• terminalId - the producer's own identifier for the physical terminal. Max 64 chars, no control characters. payware records it and never interprets it: no format, no uniqueness enforcement, and nothing about pricing or attribution depends on it.

• terminalManufacturer - device manufacturer as the terminal reports it. Max 64 chars, no control characters. Recorded for provenance. payware's internal attribution review counts each producer's sales by reported manufacturer, so a build running on another vendor's hardware stands out; it is never blocked.

Two things worth knowing:

1. It never changes what the merchant is charged. The producer's share comes out of payware's own fee, not out of a higher price for the merchant, whose fee always follows the fee hierarchy.

2. None of the three is returned. They do not appear in the create response, in get_transaction_status, in transaction history, or in any callback. What a producer earned is visible on their own dashboard and settlements - attribution is recorded against the fee, not against the transaction.

If an ISV's software made the call, the ISV is attributed and the producer is not, even when the ISV's software is running on that producer's hardware.

[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:

{ "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.

[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.

[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 delivered to whatever certificate the merchant's endpoint happens to present, which is an acceptable trade for a transaction id and an amount and not one for a shopper's home address. This endpoint is JWT-authenticated, tenant-scoped and runs over a verified channel. So the pattern is: the callback tells you the shipment is ready, and this call gives you the address to ship to.

⚠️ 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.

[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:

{
  "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
  }
}

[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.

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).

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

[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.

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

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

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

[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.

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

[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.

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

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

[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

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

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

[Merchant] Update an existing product. Only provide the fields you want to change. The tool reads the product first and sends it whole: the server resets a field a partial update leaves out (active, shippable and quickPay to FALSE, type, time zone and time to live to defaults), a server defect.

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

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

[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

[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).

[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).

[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).

[Merchant] Update an existing price schedule. Only provide fields you want to change. The tool reads the schedule (and the product's time zone) first and sends it whole: the server resets a field a partial update leaves out (the discount to 0%, the dates to today), a server defect. Premium (PRM) plan only: the server answers 403 on any other plan (for an ISV, the merchant's plan).

[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).

[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

[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).

[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).

[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).

[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).

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

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

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

[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.

[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.

[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.

[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.

[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.

[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.

[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.

[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.

[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 and the shop's label, image and terms URLs.

⚠️ 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.

[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.

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

Endpoint: POST /campaigns (PRM plan)

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

Endpoint: GET /campaigns/{campaignId}

[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)

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

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

[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)

[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.

[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)

[Merchant] Get a placement.

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

[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)

[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)

[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

[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)

[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

[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)

[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)

[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

[Merchant] Get one airing rule.

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

[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)

[Merchant] Delete one airing rule.

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

[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