Skip to main content
Glama
Sign In
Payware MCP Server

Payware MCP Server

Official
by payware
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

payware_poi_create

Creates one payment POI under a shop for payer scans, using a required shop code to attach the physical payment point to the correct merchant location.

Instructions

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

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": {
      "shopCode": "<shopCode>"
    },
    "name": "payware_poi_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoHuman-readable POI name, e.g. "Till 3" or "Gate B". Shown in the portal and in POI listings.
shopCodeYesCode of the shop this POI belongs to. Required. Find one with payware_shops_list.
partnerIdNoPartner ID from the payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.
privateKeyNoRSA private key for JWT signing. Uses the environment-specific key as default.
ttlSecondsNoPrice-session TTL in seconds - how long a price set on this POI stays claimable before it returns to IDLE. Server default 300.
useSandboxNoUse sandbox environment for testing
callbackUrlNoHTTPS URL for this POI's callbacks: poi.scanned (with the new transaction id), poi.expired (price not scanned) and the sale's TRANSACTION_FINALIZED (final status, with poiId). Signed by the ISV that set the price, otherwise the merchant. A POI without one sends no callbacks - there is no per-price callback URL. Must present a publicly-trusted TLS certificate and resolve to a public address.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.2.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavior beyond them: authorization failure mode (403 for FI principals), emitted callback events and their signing party, and the partial-failure hazard of looping. It stops short of describing the created response payload, but the behavioral disclosure is unusually rich.

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

Conciseness4/5

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

Bold lead-ins front-load the three things an agent needs (resource definition, required dependency, batch alternative), and each paragraph earns its place. The verbatim endpoint/status line is the one element that adds little for an agent that cannot see HTTP details.

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

Completeness4/5

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

For a 7-parameter mutation tool with no output schema, the description covers preconditions (shop code discovery, principal restrictions), a key param caveat, and side effects (callbacks). The main gap is that it never says what the created POI response contains, which matters given no output schema.

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

Parameters4/5

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

Schema coverage is 100%, so the base is 3, but the description adds conceptual meaning the schema cannot: ttlSeconds is "the price-session TTL, not the POI's lifetime" and governs return to IDLE, and shopCode is framed as required-and-discoverable. It reinforces rather than duplicates the schema on callbackUrl.

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

Purpose5/5

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

States a specific verb and resource ("Create a single POI") and defines what a POI is ("a physical payment point a payer scans"), plus the endpoint and expected 201. It also explicitly contrasts with payware_poi_create_batch, so an agent can distinguish it from its closest sibling without opening a schema.

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

Usage Guidelines5/5

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

Explicit routing guidance: use payware_shops_list to obtain shopCode "rather than guessing", and use payware_poi_create_batch when creating many, with a concrete reason (atomic up to 50, avoids a half-built estate). It also states a when-not condition: financial-institution principals get 403 on every POI endpoint.

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

Deploy Server

Other Tools