Payware MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

payware_operations_create_transaction

Create a new payware transaction with amount, currency, reason, and payment type (PLAIN, QR, or BARCODE), including optional callbacks, deferred transfer, and POS terminal attribution.

Instructions

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

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

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "currency": "<currency>",
      "reasonL1": "<reasonL1>"
    },
    "name": "payware_operations_create_transaction"
  }
}

Input Schema

Name	Required	Description
`shop`	No	📋 ROOT LEVEL: Shop code (if not supplied, default shop is used)
`type`	No	Transaction type
`amount`	No	Amount as currency value (e.g., 25.50 for €25.50 or '15.75' for $15.75). Can be 0 for amount-flexible transactions. Max 36 chars including decimals
`account`	No	📋 ROOT LEVEL: Account identifier (if not supplied, determined from payware portal)
`qrScale`	No	QR OPTIONS (type=QR): pixels per module, 1-100, irrelevant for SVG (default 16)
`currency`	Yes	Transaction currency (ISO 3-character code)
`qrBorder`	No	QR OPTIONS (type=QR): quiet zone around the code, in modules, 1-10 (default 4)
`qrFormat`	No	QR OPTIONS (type=QR): image format, PNG, JPG or SVG (default SVG)
`reasonL1`	Yes	Transaction grounds description (required)
`reasonL2`	No	Transaction grounds description continuation (optional)
`barFormat`	No	BARCODE OPTIONS (type=BARCODE): image format, PNG, JPG or SVG (default SVG)
`partnerId`	No	🔐 AUTHENTICATION: Partner ID from payware dashboard (not sent in API request). Uses PAYWARE_PARTNER_ID env var as default.
`qrVersion`	No	QR OPTIONS (type=QR): QR version, 1-40, higher holds more data (default 3)
`privateKey`	No	🔐 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.
`terminalId`	No	🏭 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 attribution or pricing. Make it unique within your own estate anyway - that is what lets you answer 'which terminal produced this sale' later. Not returned in any response or callback.
`timeToLive`	No	⚙️ TRANSACTION OPTIONS: Time allowed for payment initiation in seconds. Once the payer's institution has started the payment, the transaction stays ACTIVE past it until the money has moved (seconds for an instant transfer, days with deferredAllowed); never infer EXPIRED from the clock.
`useSandbox`	No	Use sandbox environment for testing
`barFontSize`	No	BARCODE OPTIONS (type=BARCODE): font size of the human-readable text, 0-24 (default 12)
`callbackUrl`	No	📋 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 are rejected (ERR_UNRESOLVABLE_CALLBACK_URL).
`barBarHeight`	No	BARCODE OPTIONS (type=BARCODE): bar height in pixels, 15-1000 (default 100)
`friendlyName`	No	📋 ROOT LEVEL: Account holder recognizable name (if not supplied, merchant alias is used)
`barModuleWidth`	No	BARCODE OPTIONS (type=BARCODE): module width in pixels, 1-10 (default 2)
`idempotencyKey`	No	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 transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.
`passbackParams`	No	📋 ROOT LEVEL: Additional parameters passed back in callbacks (max 200 chars)
`deferredAllowed`	No	⚙️ 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 also pay by an ordinary credit transfer that settles later. Not for a terminal sale: combined with producerPartnerId, terminalId or terminalManufacturer it is refused with 400 ERR_DEFERRED_TRANSFER_NOT_ALLOWED. A deferred payment stays ACTIVE (pending) until the transfer settles, which can take days and can outlast timeToLive: keep polling or wait for the callback, never treat it as expired yourself. Echoed as deferredAllowed: true when set.
`producerPartnerId`	No	🏭 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 transaction (400 ERR_INVALID_PRODUCER_ID) rather than being ignored. Omit entirely when there is no producer arrangement; never send an empty string. Selects the producer's revenue share out of payware's own fee and never changes what the merchant is charged. Not returned in any response or callback.
`qrErrorCorrection`	No	QR OPTIONS (type=QR): error correction, LOW (7%), MEDIUM (15%), QUARTILE (25%) or HIGH (30%) (default QUARTILE)
`terminalManufacturer`	No	🏭 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. Not returned in any response or callback.
`barHumanReadableLocation`	No	BARCODE OPTIONS (type=BARCODE): where the human-readable text goes (default NONE)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.2.0Nov 10, 2026

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare non-read-only, non-destructive, open-world, non-idempotent, and the description reinforces this with real behavioral consequences: a deferred payment stays ACTIVE for days past timeToLive, an unrecognised producerPartnerId hard-fails the first sale, and the three producer fields are never returned anywhere. Useful additions such as the ISV-attribution precedence rule go beyond the structured fields, though much of the deferred/producer explanation is repeated from the schema descriptions. The idempotentHint=false annotation is not contradicted, since the Idempotency-Key is an explicit opt-in described in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is well organized with bold headers and front-loads the purpose, but it is very long for a tool description and spends several paragraphs re-listing parameter groups (QR options, barcode options) whose defaults and ranges are already in the schema, plus an example JSON block. The deferred and producer sections are verbose and duplicate their own schema entries.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 29-parameter creation tool with no output schema, the description never says what a successful create returns — no mention of the transaction identifier, the QR/barcode payload, or the overall response shape, even though it references "the create response" in passing. It also omits error handling for the required parameters and says nothing about when to use this rather than process_transaction, leaving meaningful gaps despite the dense field-level detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does add one thing the flat schema does not: the grouping of parameters into root level, trData, trOptions, qrOptions, barOptions and the non-transmitted authentication block, which clarifies how the flat arguments are reassembled into the nested API call. Beyond that grouping it largely restates the per-parameter text already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ("Create a new payware transaction") and is immediately followed by a mapping of parameters to the API request shape, so the agent knows exactly what is produced. It does not, however, distinguish this from sibling tools such as payware_operations_process_transaction or cancel_transaction, so the boundary with those must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is substantial conditional guidance for individual features — when deferredAllowed is honoured versus rejected with 400 ERR_DEFERRED_TRANSFER_NOT_ALLOWED, and when producerPartnerId must be omitted. But that is field-level usage, not tool-level routing: nothing says when to call create_transaction versus process_transaction or how to proceed after creating one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server