Skip to main content
Glama

mcp-gateway

by xyz.trusteed
OverviewDiscussionsAdmin

complete_checkout

Idempotent

Complete the purchase. Collects buyer contact info via elicitation if supported. Idempotent — replay is keyed on checkout_session_id: any retry against a session that already has an order returns that same order (COMPLETED or PENDING_EXTERNAL_CONFIRMATION) without re-charging. The provided idempotency_key is recorded on the session for audit and short-circuits a repeated call with the same key.

SKYFIRE TOKEN (payment_method=KYAPAY): Requires a Skyfire pay or kya-pay token. Preferred: pass the JWT in the skyfire-pay-id request header. Alternative: pass as kyapay_token parameter. Claims validated: sub (account ID), jti (replay prevention), amount (USD, matched against cart total), cur (must be USD), sps (pricing scheme). Missing token with KYAPAY method → error. Invalid token → error 'Invalid Skyfire token'. For other payment methods (MOCK, PAYPAL) no Skyfire token is required. PAYMENT MANDATE: this tool also requires one. Send it as the payment_mandate argument if your client cannot set headers, or as an X-Payment-Mandate header. It must carry mandate_id, max_amount_cents, currency, exp, sub, aud, and its currency must match the cart's currency or the call is denied outright. The cap in max_amount_cents is enforced against the cart total. CREDENTIAL: this store needs one. Call the create_sandbox_key tool first (it is in this tool list and needs no credential), then pass the key you get back as the agent_key argument — or as an Authorization: Bearer header if your client can set headers. Do not ask a person to log in: there is no human login for this store.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
buyerNoOptional buyer contact information
agent_keyNoSandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.
cel_contextNoOptional enforcement context for Trusteed native MCP flows (no Shopify/WooCommerce/PrestaShop/Magento plugin). Providing these fields enables full evaluation of rules R004, R006, R008, R012-R013, R015-R017, R022, R026-R029. Fields are validated and signed — do not include values you cannot substantiate.
kyapay_tokenNoSkyfire pay or kya-pay JWT for autonomous payment via Skyfire (payment_method=KYAPAY). Alternative to passing the token in the skyfire-pay-id request header — the header takes precedence if both are provided. Claims required: sub, jti, amount (USD), cur=USD, sps.
payment_methodNoPayment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY requires kyapay_token. ACP (Agentic Commerce Protocol / Stripe-native settlement) is NOT enabled by default: unless MCP_ACP_NATIVE_SETTLEMENT_ENABLED=true, a non-zero non-Shopify ACP cart returns an explicit 'not enabled' response instead of a mock completion. Defaults to MOCK if not specified.
idempotency_keyYesUnique key to prevent duplicate charges on retry. Generate once per purchase attempt. Replay is enforced primarily on checkout_session_id (the existing order is returned). The first key seen for a session is recorded; reusing the same key short-circuits to the existing order.
payment_mandateNoPayment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header.
checkout_session_idYesCheckout session ID from preview_checkout (must be a valid UUID)
reconfirmed_state_hashNoSHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusYes
currencyYes
order_idYes
idempotentYes
store_nameYes
payment_urlNo
total_centsYes
external_order_idNo
checkout_session_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / agent_key
      Added value: +{
+  "description": "Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header.",
+  "type": "string"
+}
    • addedInput schema / properties / payment_mandate
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "type": "object"
+    },
+    {
+      "type": "string"
+    }
+  ],
+  "description": "Payment mandate with `mandate_id`, `max_amount_cents`, `currency`, `exp`, `sub`, `aud`. Its `currency` must match the cart's. Use this when your client cannot set an `X-Payment-Mandate` header."
+}
  2. Changed4 schema fields changed
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / buyer / additionalProperties
      Previous value: -falseNew value: +true
    • changedInput schema / properties / cel_context / additionalProperties
      Previous value: -falseNew value: +true
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
  3. Changed1 schema field changed
    • addedOutput schema / properties / payment_url
      Added value: +{
+  "type": "string"
+}
  4. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "checkout_session_id": {
+      "type": "string"
+    },
+    "currency": {
+      "type": "string"
+    },
+    "external_order_id": {
+      "type": "string"
+    },
+    "idempotent": {
+      "type": "boolean"
+    },
+    "order_id": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "COMPLETED",
+        "ALREADY_PLACED",
+        "PENDING_EXTERNAL_CONFIRMATION"
+      ],
+      "type": "string"
+    },
+    "store_name": {
+      "type": "string"
+    },
+    "total_cents": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "order_id",
+    "checkout_session_id",
+    "store_name",
+    "total_cents",
+    "currency",
+    "status",
+    "idempotent"
+  ],
+  "type": "object"
+}
  5. Changed1 schema field changed
    • addedInput schema / properties / reconfirmed_state_hash
      Added value: +{
+  "description": "SHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew.",
+  "pattern": "^[0-9a-f]{64}$",
+  "type": "string"
+}
  6. Changed4 schema fields changed
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties
      Added value: +{
+  "buyer": {
+    "additionalProperties": false,
+    "description": "Optional buyer contact information",
+    "properties": {
+      "email": {
+        "description": "Buyer email address",
+        "format": "email",
+        "type": "string"
+      },
+      "name": {
+        "description": "Buyer full name",
+        "type": "string"
+      },
+      "phone": {
+        "description": "Buyer phone number",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "cel_context": {
+    "additionalProperties": false,
+    "description": "Optional enforcement context for Trusteed native MCP flows (no Shopify/WooCommerce/PrestaShop/Magento plugin). Providing these fields enables full evaluation of rules R004, R006, R008, R012-R013, R015-R017, R022, R026-R029. Fields are validated and signed — do not include values you cannot substantiate.",
+    "properties": {
+      "agent_provider_id": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z0-9_\\-]+$",
+        "type": "string"
+      },
+      "autorenew_consent": {
+        "type": "boolean"
+      },
+      "cart_total_cents": {
+        "maximum": 100000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "completed_orders": {
+        "maximum": 1000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "completed_orders_24h": {
+        "maximum": 1000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "cross_merchant_abuse": {
+        "type": "boolean"
+      },
+      "digital_good_types": {
+        "items": {
+          "enum": [
+            "gift_card",
+            "license_key",
+            "downloadable",
+            "stored_value"
+          ],
+          "type": "string"
+        },
+        "maxItems": 10,
+        "type": "array"
+      },
+      "discount_bps": {
+        "maximum": 10000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "discount_codes_tried": {
+        "maximum": 100,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "dispute_count": {
+        "maximum": 1000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "is_b2b": {
+        "type": "boolean"
+      },
+      "is_subscription": {
+        "type": "boolean"
+      },
+      "item_count": {
+        "maximum": 10000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "key_age_hours": {
+        "maximum": 720,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "lowest_stock": {
+        "minimum": 0,
+        "type": "integer"
+      },
+      "merchant_avg_order_cents": {
+        "maximum": 100000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "merchant_orders_1h": {
+        "maximum": 1000000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "payment_method": {
+        "maxLength": 64,
+        "minLength": 1,
+        "type": "string"
+      },
+      "price_delta_bps": {
+        "maximum": 10000,
+        "minimum": -10000,
+        "type": "integer"
+      },
+      "product_categories": {
+        "items": {
+          "maxLength": 64,
+          "type": "string"
+        },
+        "maxItems": 50,
+        "type": "array"
+      },
+      "provider_confidence": {
+        "maximum": 1,
+        "minimum": 0,
+        "type": "number"
+      },
+      "purchase_order_hash": {
+        "maxLength": 128,
+        "type": "string"
+      },
+      "qty_per_sku_max": {
+        "maximum": 10000,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "refund_ratio": {
+        "maximum": 1,
+        "minimum": 0,
+        "type": "number"
+      },
+      "regulated_evidence_present": {
+        "type": "boolean"
+      },
+      "requested_scopes": {
+        "items": {
+          "maxLength": 64,
+          "type": "string"
+        },
+        "maxItems": 20,
+        "type": "array"
+      },
+      "return_policy_mismatch": {
+        "type": "boolean"
+      },
+      "shipping_freight_forwarder": {
+        "type": "boolean"
+      },
+      "shipping_po_box": {
+        "type": "boolean"
+      },
+      "stored_value_cents": {
+        "maximum": 100000000,
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  "checkout_session_id": {
+    "description": "Checkout session ID from preview_checkout (must be a valid UUID)",
+    "type": "string"
+  },
+  "idempotency_key": {
+    "description": "Unique key to prevent duplicate charges on retry. Generate once per purchase attempt. Replay is enforced primarily on checkout_session_id (the existing order is returned). The first key seen for a session is recorded; reusing the same key short-circuits to the existing order.",
+    "type": "string"
+  },
+  "kyapay_token": {
+    "description": "Skyfire pay or kya-pay JWT for autonomous payment via Skyfire (payment_method=KYAPAY). Alternative to passing the token in the skyfire-pay-id request header — the header takes precedence if both are provided. Claims required: sub, jti, amount (USD), cur=USD, sps.",
+    "type": "string"
+  },
+  "payment_method": {
+    "description": "Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY requires kyapay_token. ACP (Agentic Commerce Protocol / Stripe-native settlement) is NOT enabled by default: unless MCP_ACP_NATIVE_SETTLEMENT_ENABLED=true, a non-zero non-Shopify ACP cart returns an explicit 'not enabled' response instead of a mock completion. Defaults to MOCK if not specified.",
+    "enum": [
+      "ACP",
+      "KYAPAY",
+      "PAYPAL",
+      "MOCK"
+    ],
+    "type": "string"
+  }
+}
    • addedInput schema / required
      Added value: +[
+  "checkout_session_id",
+  "idempotency_key"
+]
  7. Changed5 schema fields changed
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties
      Removed value: -{
-  "buyer": {
-    "additionalProperties": false,
-    "description": "Optional buyer contact information",
-    "properties": {
-      "email": {
-        "description": "Buyer email address",
-        "format": "email",
-        "type": "string"
-      },
-      "name": {
-        "description": "Buyer full name",
-        "type": "string"
-      },
-      "phone": {
-        "description": "Buyer phone number",
-        "type": "string"
-      }
-    },
-    "type": "object"
-  },
-  "checkout_session_id": {
-    "description": "Checkout session ID from preview_checkout (must be a valid UUID)",
-    "type": "string"
-  },
-  "idempotency_key": {
-    "description": "Unique key to prevent duplicate charges on retry. Generate once per purchase attempt.",
-    "type": "string"
-  },
-  "kyapay_token": {
-    "description": "Skyfire pay or kya-pay JWT for autonomous payment via Skyfire (payment_method=KYAPAY). Alternative to passing the token in the skyfire-pay-id request header — the header takes precedence if both are provided. Claims required: sub, jti, amount (USD), cur=USD, sps.",
-    "type": "string"
-  },
-  "payment_method": {
-    "description": "Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY requires kyapay_token. Defaults to MOCK if not specified.",
-    "enum": [
-      "ACP",
-      "KYAPAY",
-      "PAYPAL",
-      "MOCK"
-    ],
-    "type": "string"
-  }
-}
    • removedInput schema / required
      Removed value: -[
-  "checkout_session_id",
-  "idempotency_key"
-]
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "checkout_session_id": {
-      "type": "string"
-    },
-    "currency": {
-      "type": "string"
-    },
-    "external_order_id": {
-      "type": "string"
-    },
-    "idempotent": {
-      "type": "boolean"
-    },
-    "order_id": {
-      "type": "string"
-    },
-    "status": {
-      "enum": [
-        "COMPLETED",
-        "ALREADY_PLACED",
-        "PENDING_EXTERNAL_CONFIRMATION"
-      ],
-      "type": "string"
-    },
-    "store_name": {
-      "type": "string"
-    },
-    "total_cents": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "order_id",
-    "checkout_session_id",
-    "store_name",
-    "total_cents",
-    "currency",
-    "status",
-    "idempotent"
-  ],
-  "type": "object"
-}New value: +null
  8. First observed

TDQS

A5/5.0
Behavior5/5

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

Annotations only state idempotentHint=true and destructiveHint=false. The description goes far beyond by detailing idempotency behavior (replay keyed on checkout_session_id, returns existing order without re-charging), error cases (missing/invalid token), enforcement of payment mandate caps, and credential requirements. This is substantial behavioral disclosure that annotations do not provide.

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

Conciseness5/5

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

Though long, every sentence carries essential information. It is front-loaded with the core purpose and idempotency, then logically groups token, mandate, and credential requirements. No filler or redundancy; the structure aids scanning and comprehension.

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

Completeness5/5

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

Given the complexity of 9 parameters, nested objects, an output schema, and the need for credentials/mandates, the description covers all critical aspects: idempotency, token validation, mandate enforcement, credential acquisition, reconfirmation, and error handling. It also references the create_sandbox_key tool in the same list. Nothing an agent needs to call this correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For example, it explains idempotency_key's role in short-circuiting, kyapay_token's required claims and precedence over header, payment_method's defaults and ACP behavior, payment_mandate's purpose and header alternative, agent_key's use when headers unavailable, and reconfirmed_state_hash's condition for use. This is far beyond schema descriptions.

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+resource ('Complete the purchase') and distinguishes itself from siblings like preview_checkout and ucp_* checkout tools by focusing on the final completion step. It also clarifies it collects buyer contact info via elicitation, adding specificity.

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?

Provides explicit when-to-use instructions, including calling create_sandbox_key first, when Skyfire token is required (KYAPAY) vs not (MOCK, PAYPAL), and that no human login exists. It also explains the idempotency key usage and the reconfirmation requirement, giving clear conditions for correct invocation.

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

All mcp-gateway toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources