# Supplier Payment Decision Agent: complete public handbook Public documentation only. Reading this handbook or downloading configuration never connects a client, installs software, registers a key, evaluates a supplier or pays anything. # Supplier Payment Decision Agent: buyer quickstart The service recommends; it never moves invoice money or provides bank Confirmation of Payee. A valid IBAN checksum does not prove account ownership. Document matches compare supplied PO/GRN/invoice data, not independently authenticated ERP records. Confidence 1.0 is a rule result, not certainty of safety. ## Try a synthetic example without paying Use-case guide: https://supplier-payment-verifier-production.up.railway.app/use-cases/supplier-invoice-verification Versioned offline scenarios: https://supplier-payment-verifier-production.up.railway.app/examples.json (assumed outcomes, not executed checks). GET https://supplier-payment-verifier-production.up.railway.app/demo The fixed response is prominently marked SYNTHETIC_ILLUSTRATION, not a live verification. It accepts no supplier inputs and does not contact registries, register keys or move money. ## Runnable REST buyer Public MIT-licensed standalone client: https://github.com/LKennedyShare/supplier-payment-assistant python -m pip install supplier-payment-assistant supplier-payment-assistant --demo # Completely offline: generates an RSA signature and prints a clearly labelled illustrative response. Prepare an unsigned JSON request with transaction_id, supplier, invoice, purchase_order and goods_receipt; omit signature. Keep a stable transaction_id for the same business request. See /schemas/decision.schema.json. Do not submit the synthetic placeholder company/VAT as if it were a real supplier. supplier-payment-assistant https://supplier-payment-verifier-production.up.railway.app --request .\invoice.json # Inspection only: fetches empty x402 quote probes for both operations. No wallet key or payment signing. To pay, set X402_CLIENT_PRIVATE_KEY in your local shell to a throwaway wallet funded with a small USDC balance on the quoted network. Never put a private key in source code, a prompt, request JSON or a log. supplier-payment-assistant https://supplier-payment-verifier-production.up.railway.app --request .\invoice.json --pay --max-usdc 0.055 Explicit --pay permits one paid retry for registration (0.005 USDC) and one decision (0.05 USDC), at most 0.055 USDC combined. Base mainnet spends real USDC. Quotes, scheme, token contract, network and remaining budget are validated before signing; redirects are refused. No automatic payment retries. The RSA signing key is ephemeral: a new public key/key_id is generated per run. The wallet is separate and identifies the tenant. A later rerun may pay registration again. Partial failures report authorized and confirmed spend; missing settlement metadata is unconfirmed and stops the flow. Python integration: from supplier_payment_assistant import run_live, PaymentRequest. run_live(base_url, unsigned_request) only inspects quotes; pay=True explicitly authorizes service fees. MIT covers the client code, not service data or API usage terms. ## LangChain and OpenAI Agents SDK python -m pip install "supplier-payment-assistant[langchain,openai]>=0.2.0" from supplier_payment_assistant import SupplierPaymentTools session = SupplierPaymentTools() langchain_tools = session.langchain_tools() openai_tools = session.openai_tools() Default tools: offline_demo and inspect_supplier. Paid verification is exposed only with an operator-defined approval_policy comparing validated canonical request digests to trusted records. The model cannot approve payments or set wallet, URL or budget parameters. Retain one instance across calls: 0.055 USDC cumulative reservation ceiling, one paid attempt by default; failures retain reservations. Limits are in-memory and reset on recreation/restart: use durable external policy/budgets for production. Invoice data and results may reach your chosen model/tracing provider; obtain authorization and configure privacy controls. No invoice money is moved. Runnable offline framework examples: https://github.com/LKennedyShare/supplier-payment-assistant/tree/main/examples ## Exact request signing Use PaymentRequest.model_validate with a placeholder signature, then PaymentRequest.signed_body(). This normalizes Decimal fields and serializes sorted-key compact JSON excluding signature. Sign those bytes using RSA-PSS, SHA-256, MGF1(SHA-256), salt_length=PSS.DIGEST_LENGTH. The buyer client does this automatically. Hand-signing the original JSON without model normalization can produce a signature mismatch. ## MCP Complete public handbook: https://supplier-payment-verifier-production.up.railway.app/llms-full.txt VS Code download: https://supplier-payment-verifier-production.up.railway.app/integrations/vscode-mcp.json (merge into .vscode\mcp.json). Cursor download: https://supplier-payment-verifier-production.up.railway.app/integrations/cursor-mcp.json (merge into .cursor\mcp.json). Operator: inspect the URL and review/merge the entry into existing configuration; do not overwrite other servers. Downloading never connects, auto-installs, registers keys or pays. Configuration trust approval is not payment approval. All supplier-operation MCP tools are paid; the public synthetic demo is HTTP-only and the offline buyer demo is client-only, not a free MCP tool. Endpoint: https://supplier-payment-verifier-production.up.railway.app/mcp/ Use tools/list as the exact runtime schema. Check tools wrap their payload in request; the decision tool uses payment_request; key registration stays flat: {"name": "check_iban", "arguments": {"request": {"iban": "IE29AIBK93115212345678"}}} {"name": "decide_supplier_payment", "arguments": {"payment_request": ""}} A normal MCP connection does not supply a wallet. An x402-capable MCP client reads the payment-required tool result, then retries with _meta['x402/payment']; successful settlement is in _meta['x402/payment-response']. ## A2A (JSON-RPC 0.3 binding) POST https://supplier-payment-verifier-production.up.railway.app/a2a with method message/send and one JSON data part: {"jsonrpc": "2.0", "id": "check-1", "method": "message/send", "params": {"message": {"kind": "message", "messageId": "message-1", "role": "user", "parts": [{"kind": "data", "data": {"operation": "check_iban", "request": {"iban": "IE29AIBK93115212345678"}}}]}}} Use operation=register_signing_key, then operation=decide_supplier_payment with the same flat REST request objects. Each operation is priced as its REST counterpart. Unwrapped legacy verification messages still return RELEASE/REVIEW/BLOCK/INSUFFICIENT_EVIDENCE, not the five-gate decision. Unpaid A2A calls return HTTP 200 with task input-required and x402.payment.required metadata. Retry with PAYMENT-SIGNATURE. Results include settlement receipts; failed settlement withholds artifacts. tasks/get reads completed tasks for the paying tenant; it retains the configured A2A verification-call price (not the cheaper REST get-verification price). ## Failures and limits HTTP 400/422 means invalid input, 409 means transaction/key conflict, 429 means wait and honor Retry-After; no automatic payment retry. A paid call returning FLAG_FOR_HUMAN_REVIEW is a valid billable decision, not a payment-processing error. Provider outages cannot produce EXECUTE_PAYMENT. x402 pays for this service only. execution_payload contains advisory invoice details: this client never submits them to a bank. Keep customer-controlled payment approval and account-ownership checks. ## Editor configuration: review and merge GET /integrations/vscode-mcp.json provides the standard .vscode\mcp.json servers object. GET /integrations/cursor-mcp.json provides the .cursor\mcp.json mcpServers object. Both are attachment downloads named mcp.json. An operator must inspect the exact configured /mcp/ URL and merge the entry into existing configuration, not overwrite other servers. No commands, environment variables, credentials, authorization headers, trust bypasses or payment flags are included. Configuration trust approval is not payment approval. A generic MCP client cannot pay x402 merely by connecting. All supplier-operation MCP tools are paid; there are no free demo MCP tools. The public synthetic demo is HTTP-only; the buyer's offline demo is client-only. ## Contracts and assurance boundaries Strict REST requests are flat model objects, not request/payment_request envelopes; unknown fields are forbidden by the input schemas below. MCP check tools use arguments.request, the decision uses arguments.payment_request, and register_signing_key uses flat arguments.key_id/public_key_pem. Use the full runtime MCP schemas below, especially for legacy tools. The legacy POST /v1/verifications and verify_supplier_payment contract has four outcomes: RELEASE, REVIEW, BLOCK, INSUFFICIENT_EVIDENCE. get_verification retrieves that contract. Do not confuse it with the five-gate decide_supplier_payment contract: CRO, VIES_VAT, CONFIRMATION_OF_PAYEE, ERP_THREE_WAY_MATCH, A2A_SIGNATURE, returning EXECUTE_PAYMENT, REJECT_PAYMENT or FLAG_FOR_HUMAN_REVIEW. Neither contract executes a bank payment. IBAN validity is not account ownership. CONFIRMATION_OF_PAYEE compares payee name to CRO legal name plus IBAN validation, not bank Confirmation of Payee (CoP). ERP_THREE_WAY_MATCH compares supplied documents, not independently authenticated ERP records. Confidence 1.0 means the implemented rules passed, not guaranteed safety. A signature authenticates the signer, not the truth of supplied evidence. ## Signing and owner approval Generate an ephemeral RSA key (at least 2048 bits); register only its public PEM and key_id, then use the same payer tenant for the signed decision. Keep the private RSA key local and separate from the wallet. Validate through PaymentRequest with a placeholder signature, then sign PaymentRequest.signed_body(): model-normalized Decimal values, sorted keys, compact canonical JSON excluding signature. RSA-PSS with SHA-256, MGF1(SHA-256), digest-length salt (PSS.DIGEST_LENGTH), then base64 into signature_b64. Do not sign the raw unnormalized input JSON. Explicit maximum 0.055 USDC covers one 0.005 registration plus one 0.05 decision service fee, not invoice money. A rerun may incur registration again. Owner/operator approval_policy is required to expose paid framework tools; by default paid framework tools are absent. Compare the validated canonical request digest against a trusted owner-approved record, never a model assertion. Keep wallet, endpoint and budget outside model control. In-memory cumulative budgets are not daily or durable budgets and reset on restart/recreation; use external durable controls in production. Privacy: invoice inputs and results can reach your selected LLM and tracing providers. Obtain authorization and configure redaction, retention and access controls. Never publish private invoice data, wallet keys, signing secrets or credentials in prompts, traces or configuration downloads. ## x402 protocol and transport payment mapping REST: an unpaid request returns HTTP 402 with a JSON requirements body and PAYMENT-REQUIRED header. Validate x402Version, accepts.scheme, network, asset, payTo, amount and maxTimeoutSeconds against owner policy and remaining budget before signing. Amounts are atomic USDC (6 decimals), not invoice currency. Retry explicitly with PAYMENT-SIGNATURE (legacy X-PAYMENT is supported); successful settlement uses PAYMENT-RESPONSE (and legacy X-PAYMENT-RESPONSE). Missing receipts are unconfirmed, not proof of settlement. Do not silently retry paid calls. MCP: payment-required is a tool result (isError/structuredContent), not free execution. Supply the payment in request _meta['x402/payment']; settlement is _meta['x402/payment-response']. HTTP payment headers are a fallback. Connecting, tools/list, or trusting a server does not authorize spend. A2A implements the JSON-RPC 0.3 binding (jsonrpc='2.0'), not A2A 1.0: POST /a2a, method message/send, exactly one JSON data part containing only operation (exact tool name) and request (flat REST body). No selector means the legacy verification contract. Unpaid responses use HTTP 200 task input-required with x402.payment.status='payment-required' and x402.payment.required metadata. Retry with PAYMENT-SIGNATURE. Settled results use x402.payment.status='payment-completed' and x402.payment.receipts. Failed settlement withholds artifacts. tasks/get is tenant-scoped and costs the configured A2A verification-call fee, not the cheaper REST retrieval fee. ## Catalogue: exact operation prices, complete public schemas and examples ### check_iban: POST /v1/checks/iban — 0.005 USDC (5000 atomic) REST, MCP and selected A2A operation have the same service fee. Cheapest call. Validates an IBAN (ISO 13616 mod-97 checksum, length and country) before you pay it. Returns PASSED or FAILED with a reason code. Irish (IE) IBANs pass by default. Complete flat REST input schema: { "additionalProperties": false, "properties": { "iban": { "description": "IBAN to validate (spaces allowed).", "maxLength": 40, "minLength": 5, "title": "Iban", "type": "string" } }, "required": [ "iban" ], "title": "IbanCheckRequest", "type": "object" } MCP argument example: { "name": "check_iban", "arguments": { "request": { "iban": "IE29AIBK93115212345678" } } } Illustrative output only, not a live result: { "check": "IBAN", "outcome": "PASSED", "checked_at": "2026-10-15T12:00:00Z", "reason_code": "IBAN_VALID", "iban": "IE29AIBK93115212345678", "country": "IE", "valid": true } ### check_vat: POST /v1/checks/vat — 0.01 USDC (10000 atomic) REST, MCP and selected A2A operation have the same service fee. Validates the Irish VAT number format and check letter, then confirms registration live with EU VIES. Returns PASSED, FAILED or UNAVAILABLE (VIES outage) with a reason code. Complete flat REST input schema: { "additionalProperties": false, "properties": { "vat_number": { "description": "Irish VAT number, with or without the IE prefix.", "maxLength": 20, "minLength": 2, "title": "Vat Number", "type": "string" } }, "required": [ "vat_number" ], "title": "VatCheckRequest", "type": "object" } MCP argument example: { "name": "check_vat", "arguments": { "request": { "vat_number": "IE6388047V" } } } Illustrative output only, not a live result: { "check": "VIES_VAT", "outcome": "PASSED", "checked_at": "2026-10-15T12:00:00Z", "reason_code": "VAT_VALID", "consultation_number": null, "agent_audit_receipt": { "vies_timestamp": "2026-10-15T12:00:00Z", "raw_response_hash": "", "agent_signature": "", "key_id": "" } } ### check_company: POST /v1/checks/company — 0.01 USDC (10000 atomic) REST, MCP and selected A2A operation have the same service fee. Looks up an Irish company by CRO number in the Companies Registration Office open data. PASSED only if the company status is NORMAL; dissolved, liquidated or unknown companies FAIL. Returns the registered name. Complete flat REST input schema: { "additionalProperties": false, "properties": { "cro_number": { "description": "Irish CRO company number.", "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" } }, "required": [ "cro_number" ], "title": "CompanyCheckRequest", "type": "object" } MCP argument example: { "name": "check_company", "arguments": { "request": { "cro_number": "123456" } } } Illustrative output only, not a live result: { "check": "CRO", "outcome": "PASSED", "checked_at": "2026-10-15T12:00:00Z", "reason_code": "CRO_NORMAL", "registered_name": "EXAMPLE SUPPLIER DESIGNATED ACTIVITY COMPANY" } ### check_three_way_match: POST /v1/checks/three-way-match — 0.02 USDC (20000 atomic) REST, MCP and selected A2A operation have the same service fee. Checks that a purchase order, goods receipt and invoice agree on supplier, currency, amount, line items, unit prices and quantities received. Stateless; you attach the documents. Checks caller-supplied documents, not independently verified ERP records. Complete flat REST input schema: { "$defs": { "GoodsReceipt": { "additionalProperties": false, "properties": { "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "received": { "items": { "$ref": "#/$defs/ReceivedLine" }, "minItems": 1, "title": "Received", "type": "array" } }, "required": [ "grn_number", "po_number", "supplier_cro_number", "received" ], "title": "GoodsReceipt", "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "invoice_number": { "minLength": 1, "title": "Invoice Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" }, "payee_name": { "maxLength": 300, "minLength": 1, "title": "Payee Name", "type": "string" } }, "required": [ "po_number", "grn_number", "invoice_number", "amount", "currency", "line_items", "payee_name" ], "title": "Invoice", "type": "object" }, "LineItem": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Unit Price" } }, "required": [ "sku", "quantity", "unit_price" ], "title": "LineItem", "type": "object" }, "PurchaseOrder": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" } }, "required": [ "po_number", "supplier_cro_number", "amount", "currency", "line_items" ], "title": "PurchaseOrder", "type": "object" }, "ReceivedLine": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" } }, "required": [ "sku", "quantity" ], "title": "ReceivedLine", "type": "object" } }, "additionalProperties": false, "properties": { "supplier_cro_number": { "maxLength": 16, "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "invoice": { "$ref": "#/$defs/Invoice" }, "purchase_order": { "$ref": "#/$defs/PurchaseOrder" }, "goods_receipt": { "$ref": "#/$defs/GoodsReceipt" } }, "required": [ "supplier_cro_number", "invoice", "purchase_order", "goods_receipt" ], "title": "ThreeWayMatchRequest", "type": "object" } MCP argument example: { "name": "check_three_way_match", "arguments": { "request": { "supplier_cro_number": "123456", "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] } } } } Illustrative output only, not a live result: { "check": "THREE_WAY_MATCH", "outcome": "PASSED", "checked_at": "2026-10-15T12:00:00Z", "reason_code": "THREE_WAY_MATCH" } ### decide_supplier_payment: POST /v1/payment-decisions — 0.05 USDC (50000 atomic) REST, MCP and selected A2A operation have the same service fee. Flagship. Independent third-party decision for an Irish supplier invoice. Runs five gates (CRO status NORMAL, EU VIES VAT, payee-name and IBAN check, PO/GRN/invoice 3-way match, RSA signature) and returns exactly one of EXECUTE_PAYMENT, REJECT_PAYMENT or FLAG_FOR_HUMAN_REVIEW with per-check results, reason codes and a confidence score. The legacy CONFIRMATION_OF_PAYEE result means a payee-name comparison with the CRO legal name and IBAN validation, not bank Confirmation of Payee. ERP_THREE_WAY_MATCH compares caller-supplied documents, not independently verified ERP records. Decides only; never moves money. Register a signing key first via /v1/agent-keys. Complete flat REST input schema: { "$defs": { "GoodsReceipt": { "additionalProperties": false, "properties": { "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "received": { "items": { "$ref": "#/$defs/ReceivedLine" }, "minItems": 1, "title": "Received", "type": "array" } }, "required": [ "grn_number", "po_number", "supplier_cro_number", "received" ], "title": "GoodsReceipt", "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "invoice_number": { "minLength": 1, "title": "Invoice Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" }, "payee_name": { "maxLength": 300, "minLength": 1, "title": "Payee Name", "type": "string" } }, "required": [ "po_number", "grn_number", "invoice_number", "amount", "currency", "line_items", "payee_name" ], "title": "Invoice", "type": "object" }, "LineItem": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Unit Price" } }, "required": [ "sku", "quantity", "unit_price" ], "title": "LineItem", "type": "object" }, "PurchaseOrder": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" } }, "required": [ "po_number", "supplier_cro_number", "amount", "currency", "line_items" ], "title": "PurchaseOrder", "type": "object" }, "ReceivedLine": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" } }, "required": [ "sku", "quantity" ], "title": "ReceivedLine", "type": "object" }, "SignatureEnvelope": { "additionalProperties": false, "description": "RSA signature over the canonical JSON of the request body, plus mTLS evidence.", "properties": { "key_id": { "minLength": 1, "title": "Key Id", "type": "string" }, "signature_b64": { "minLength": 1, "title": "Signature B64", "type": "string" }, "mtls_cert_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mtls Cert Fingerprint" } }, "required": [ "key_id", "signature_b64" ], "title": "SignatureEnvelope", "type": "object" }, "Supplier": { "additionalProperties": false, "properties": { "cro_number": { "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" }, "vat_number": { "maxLength": 20, "minLength": 1, "title": "Vat Number", "type": "string" }, "iban": { "maxLength": 40, "minLength": 1, "title": "Iban", "type": "string" } }, "required": [ "cro_number", "vat_number", "iban" ], "title": "Supplier", "type": "object" } }, "additionalProperties": false, "properties": { "transaction_id": { "maxLength": 64, "minLength": 1, "title": "Transaction Id", "type": "string" }, "supplier": { "$ref": "#/$defs/Supplier" }, "invoice": { "$ref": "#/$defs/Invoice" }, "purchase_order": { "$ref": "#/$defs/PurchaseOrder" }, "goods_receipt": { "$ref": "#/$defs/GoodsReceipt" }, "signature": { "$ref": "#/$defs/SignatureEnvelope" } }, "required": [ "transaction_id", "supplier", "invoice", "purchase_order", "goods_receipt", "signature" ], "title": "PaymentRequest", "type": "object" } MCP argument example: { "name": "decide_supplier_payment", "arguments": { "payment_request": { "transaction_id": "inv-2026-0042", "supplier": { "cro_number": "123456", "vat_number": "IE6388047V", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] }, "signature": { "key_id": "my-key-1", "signature_b64": "" } } } } Illustrative output only, not a live result: { "agent_id": "spv-payment-decision-agent", "timestamp": "2026-10-15T12:00:00Z", "transaction_id": "inv-2026-0042", "supplier": { "cro_number": "123456", "vat_number": "IE6388047V", "iban": "IE29AIBK93115212345678" }, "verification_results": { "CRO": "PASSED", "VIES_VAT": "PASSED", "CONFIRMATION_OF_PAYEE": "PASSED", "ERP_THREE_WAY_MATCH": "PASSED", "A2A_SIGNATURE": "PASSED" }, "decision": "EXECUTE_PAYMENT", "confidence_score": 1.0, "execution_payload": { "amount": "1000.00", "currency": "EUR", "creditor_iban": "IE29AIBK93115212345678" }, "reason_codes": [], "vies_consultation_number": null, "vies_audit_receipt": null } ### register_signing_key: POST /v1/agent-keys — 0.005 USDC (5000 atomic) REST, MCP and selected A2A operation have the same service fee. Registers an RSA public key (2048-bit or larger, PEM) used to sign payment-decision requests. Keys are immutable per tenant; rotate by registering a new key_id. Complete flat REST input schema: { "additionalProperties": false, "properties": { "key_id": { "maxLength": 128, "minLength": 1, "title": "Key Id", "type": "string" }, "public_key_pem": { "maxLength": 16384, "minLength": 1, "title": "Public Key Pem", "type": "string" } }, "required": [ "key_id", "public_key_pem" ], "title": "SigningKeyRequest", "type": "object" } MCP argument example: { "name": "register_signing_key", "arguments": { "key_id": "my-key-1", "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } Illustrative output only, not a live result: { "key_id": "my-key-1", "registered": true } ## Legacy surface prices POST /v1/verifications; MCP verify_supplier_payment; A2A legacy message/send and tasks/get: 0.05 USDC (50000 atomic) GET /v1/verifications/{verification_id}; MCP get_verification: 0.005 USDC (5000 atomic) ## Complete runtime MCP tool definitions (metadata only; no tools invoked) [ { "name": "check_iban", "description": "Cheapest call. Validates an IBAN (ISO 13616 mod-97 checksum, length and country) before you pay it. Returns PASSED or FAILED with a reason code. Irish (IE) IBANs pass by default. Price: 0.005 USDC.", "inputSchema": { "$defs": { "IbanCheckRequest": { "additionalProperties": false, "properties": { "iban": { "description": "IBAN to validate (spaces allowed).", "maxLength": 40, "minLength": 5, "title": "Iban", "type": "string" } }, "required": [ "iban" ], "title": "IbanCheckRequest", "type": "object" } }, "properties": { "request": { "$ref": "#/$defs/IbanCheckRequest" } }, "required": [ "request" ], "title": "check_ibanArguments", "type": "object" }, "examples": [ { "arguments": { "request": { "iban": "IE29AIBK93115212345678" } } } ] }, { "name": "register_signing_key", "description": "Registers an RSA public key (2048-bit or larger, PEM) used to sign payment-decision requests. Keys are immutable per tenant; rotate by registering a new key_id. Price: 0.005 USDC.", "inputSchema": { "additionalProperties": false, "properties": { "key_id": { "maxLength": 128, "minLength": 1, "title": "Key Id", "type": "string" }, "public_key_pem": { "maxLength": 16384, "minLength": 1, "title": "Public Key Pem", "type": "string" } }, "required": [ "key_id", "public_key_pem" ], "title": "register_signing_keyArguments", "type": "object" }, "examples": [ { "arguments": { "key_id": "my-key-1", "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } ] }, { "name": "check_vat", "description": "Validates the Irish VAT number format and check letter, then confirms registration live with EU VIES. Returns PASSED, FAILED or UNAVAILABLE (VIES outage) with a reason code. Price: 0.01 USDC.", "inputSchema": { "$defs": { "VatCheckRequest": { "additionalProperties": false, "properties": { "vat_number": { "description": "Irish VAT number, with or without the IE prefix.", "maxLength": 20, "minLength": 2, "title": "Vat Number", "type": "string" } }, "required": [ "vat_number" ], "title": "VatCheckRequest", "type": "object" } }, "properties": { "request": { "$ref": "#/$defs/VatCheckRequest" } }, "required": [ "request" ], "title": "check_vatArguments", "type": "object" }, "examples": [ { "arguments": { "request": { "vat_number": "IE6388047V" } } } ] }, { "name": "check_company", "description": "Looks up an Irish company by CRO number in the Companies Registration Office open data. PASSED only if the company status is NORMAL; dissolved, liquidated or unknown companies FAIL. Returns the registered name. Price: 0.01 USDC.", "inputSchema": { "$defs": { "CompanyCheckRequest": { "additionalProperties": false, "properties": { "cro_number": { "description": "Irish CRO company number.", "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" } }, "required": [ "cro_number" ], "title": "CompanyCheckRequest", "type": "object" } }, "properties": { "request": { "$ref": "#/$defs/CompanyCheckRequest" } }, "required": [ "request" ], "title": "check_companyArguments", "type": "object" }, "examples": [ { "arguments": { "request": { "cro_number": "123456" } } } ] }, { "name": "check_three_way_match", "description": "Checks that a purchase order, goods receipt and invoice agree on supplier, currency, amount, line items, unit prices and quantities received. Stateless; you attach the documents. Checks caller-supplied documents, not independently verified ERP records. Price: 0.02 USDC.", "inputSchema": { "$defs": { "GoodsReceipt": { "additionalProperties": false, "properties": { "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "received": { "items": { "$ref": "#/$defs/ReceivedLine" }, "minItems": 1, "title": "Received", "type": "array" } }, "required": [ "grn_number", "po_number", "supplier_cro_number", "received" ], "title": "GoodsReceipt", "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "invoice_number": { "minLength": 1, "title": "Invoice Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" }, "payee_name": { "maxLength": 300, "minLength": 1, "title": "Payee Name", "type": "string" } }, "required": [ "po_number", "grn_number", "invoice_number", "amount", "currency", "line_items", "payee_name" ], "title": "Invoice", "type": "object" }, "LineItem": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Unit Price" } }, "required": [ "sku", "quantity", "unit_price" ], "title": "LineItem", "type": "object" }, "PurchaseOrder": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" } }, "required": [ "po_number", "supplier_cro_number", "amount", "currency", "line_items" ], "title": "PurchaseOrder", "type": "object" }, "ReceivedLine": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" } }, "required": [ "sku", "quantity" ], "title": "ReceivedLine", "type": "object" }, "ThreeWayMatchRequest": { "additionalProperties": false, "properties": { "supplier_cro_number": { "maxLength": 16, "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "invoice": { "$ref": "#/$defs/Invoice" }, "purchase_order": { "$ref": "#/$defs/PurchaseOrder" }, "goods_receipt": { "$ref": "#/$defs/GoodsReceipt" } }, "required": [ "supplier_cro_number", "invoice", "purchase_order", "goods_receipt" ], "title": "ThreeWayMatchRequest", "type": "object" } }, "properties": { "request": { "$ref": "#/$defs/ThreeWayMatchRequest" } }, "required": [ "request" ], "title": "check_three_way_matchArguments", "type": "object" }, "examples": [ { "arguments": { "request": { "supplier_cro_number": "123456", "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] } } } } ] }, { "name": "decide_supplier_payment", "description": "Flagship. Independent third-party decision for an Irish supplier invoice. Runs five gates (CRO status NORMAL, EU VIES VAT, payee-name and IBAN check, PO/GRN/invoice 3-way match, RSA signature) and returns exactly one of EXECUTE_PAYMENT, REJECT_PAYMENT or FLAG_FOR_HUMAN_REVIEW with per-check results, reason codes and a confidence score. The legacy CONFIRMATION_OF_PAYEE result means a payee-name comparison with the CRO legal name and IBAN validation, not bank Confirmation of Payee. ERP_THREE_WAY_MATCH compares caller-supplied documents, not independently verified ERP records. Decides only; never moves money. Register a signing key first via /v1/agent-keys. Price: 0.05 USDC.", "inputSchema": { "$defs": { "GoodsReceipt": { "additionalProperties": false, "properties": { "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "received": { "items": { "$ref": "#/$defs/ReceivedLine" }, "minItems": 1, "title": "Received", "type": "array" } }, "required": [ "grn_number", "po_number", "supplier_cro_number", "received" ], "title": "GoodsReceipt", "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "invoice_number": { "minLength": 1, "title": "Invoice Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" }, "payee_name": { "maxLength": 300, "minLength": 1, "title": "Payee Name", "type": "string" } }, "required": [ "po_number", "grn_number", "invoice_number", "amount", "currency", "line_items", "payee_name" ], "title": "Invoice", "type": "object" }, "LineItem": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Unit Price" } }, "required": [ "sku", "quantity", "unit_price" ], "title": "LineItem", "type": "object" }, "PaymentRequest": { "additionalProperties": false, "properties": { "transaction_id": { "maxLength": 64, "minLength": 1, "title": "Transaction Id", "type": "string" }, "supplier": { "$ref": "#/$defs/Supplier" }, "invoice": { "$ref": "#/$defs/Invoice" }, "purchase_order": { "$ref": "#/$defs/PurchaseOrder" }, "goods_receipt": { "$ref": "#/$defs/GoodsReceipt" }, "signature": { "$ref": "#/$defs/SignatureEnvelope" } }, "required": [ "transaction_id", "supplier", "invoice", "purchase_order", "goods_receipt", "signature" ], "title": "PaymentRequest", "type": "object" }, "PurchaseOrder": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/$defs/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" } }, "required": [ "po_number", "supplier_cro_number", "amount", "currency", "line_items" ], "title": "PurchaseOrder", "type": "object" }, "ReceivedLine": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" } }, "required": [ "sku", "quantity" ], "title": "ReceivedLine", "type": "object" }, "SignatureEnvelope": { "additionalProperties": false, "description": "RSA signature over the canonical JSON of the request body, plus mTLS evidence.", "properties": { "key_id": { "minLength": 1, "title": "Key Id", "type": "string" }, "signature_b64": { "minLength": 1, "title": "Signature B64", "type": "string" }, "mtls_cert_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mtls Cert Fingerprint" } }, "required": [ "key_id", "signature_b64" ], "title": "SignatureEnvelope", "type": "object" }, "Supplier": { "additionalProperties": false, "properties": { "cro_number": { "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" }, "vat_number": { "maxLength": 20, "minLength": 1, "title": "Vat Number", "type": "string" }, "iban": { "maxLength": 40, "minLength": 1, "title": "Iban", "type": "string" } }, "required": [ "cro_number", "vat_number", "iban" ], "title": "Supplier", "type": "object" } }, "properties": { "payment_request": { "$ref": "#/$defs/PaymentRequest" } }, "required": [ "payment_request" ], "title": "decide_supplier_paymentArguments", "type": "object" }, "examples": [ { "arguments": { "payment_request": { "transaction_id": "inv-2026-0042", "supplier": { "cro_number": "123456", "vat_number": "IE6388047V", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] }, "signature": { "key_id": "my-key-1", "signature_b64": "" } } } } ] }, { "name": "verify_supplier_payment", "description": "Verify supplier identity, CRO registration and VAT status, then return the canonical advisory decision.", "inputSchema": { "$defs": { "AssertionsInput": { "additionalProperties": false, "properties": { "supplier_approved": { "title": "Supplier Approved", "type": "boolean" }, "po_matched": { "title": "Po Matched", "type": "boolean" }, "amount_within_po": { "title": "Amount Within Po", "type": "boolean" }, "currency_matched": { "title": "Currency Matched", "type": "boolean" }, "invoice_supplier_matched": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Invoice Supplier Matched" }, "assertion_source": { "anyOf": [ { "enum": [ "SAP", "D365", "ORACLE", "NETSUITE", "OTHER" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Assertion Source" } }, "required": [ "supplier_approved", "po_matched", "amount_within_po", "currency_matched" ], "title": "AssertionsInput", "type": "object" }, "CallbackInput": { "additionalProperties": false, "properties": { "url": { "title": "Url", "type": "string" }, "authentication_reference": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "default": null, "title": "Authentication Reference" } }, "required": [ "url" ], "title": "CallbackInput", "type": "object" }, "EvidenceInput": { "additionalProperties": false, "properties": { "type": { "enum": [ "INVOICE", "PURCHASE_ORDER", "SUPPLIER_MASTER", "BANK_CHANGE_REQUEST", "OTHER" ], "title": "Type", "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "title": "Sha256", "type": "string" }, "observed_at": { "title": "Observed At", "type": "string" }, "content_uri": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Uri" }, "media_type": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "default": null, "title": "Media Type" } }, "required": [ "type", "sha256", "observed_at" ], "title": "EvidenceInput", "type": "object" }, "PaymentDestinationInput": { "additionalProperties": false, "properties": { "fingerprint": { "maxLength": 256, "minLength": 32, "title": "Fingerprint", "type": "string" }, "fingerprint_algorithm": { "const": "HMAC-SHA-256", "title": "Fingerprint Algorithm", "type": "string" }, "country_code": { "pattern": "^[A-Z]{2}$", "title": "Country Code", "type": "string" }, "beneficiary_name": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "default": null, "title": "Beneficiary Name" }, "is_declared_change": { "default": false, "title": "Is Declared Change", "type": "boolean" } }, "required": [ "fingerprint", "fingerprint_algorithm", "country_code" ], "title": "PaymentDestinationInput", "type": "object" }, "SupplierInput": { "additionalProperties": false, "properties": { "customer_supplier_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Customer Supplier Id" }, "claimed_legal_name": { "maxLength": 300, "minLength": 1, "title": "Claimed Legal Name", "type": "string" }, "country_code": { "pattern": "^[A-Z]{2}$", "title": "Country Code", "type": "string" }, "company_registration_number": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "default": null, "title": "Company Registration Number" }, "vat_number": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "default": null, "title": "Vat Number" }, "lei": { "anyOf": [ { "pattern": "^[A-Z0-9]{20}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Lei" }, "claimed_address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Claimed Address" } }, "required": [ "claimed_legal_name", "country_code" ], "title": "SupplierInput", "type": "object" }, "TransactionInput": { "additionalProperties": false, "properties": { "invoice_id": { "maxLength": 128, "minLength": 1, "title": "Invoice Id", "type": "string" }, "purchase_order_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Purchase Order Id" }, "amount": { "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,4})?$", "title": "Amount", "type": "string" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "invoice_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invoice Date" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" } }, "required": [ "invoice_id", "amount", "currency" ], "title": "TransactionInput", "type": "object" } }, "properties": { "schema_version": { "const": "1.0", "title": "Schema Version", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" }, "policy_id": { "const": "eu-b2b-payment-v1", "title": "Policy Id", "type": "string" }, "supplier": { "$ref": "#/$defs/SupplierInput" }, "transaction": { "anyOf": [ { "$ref": "#/$defs/TransactionInput" }, { "type": "null" } ], "default": null }, "customer_assertions": { "anyOf": [ { "$ref": "#/$defs/AssertionsInput" }, { "type": "null" } ], "default": null }, "payment_destination": { "anyOf": [ { "$ref": "#/$defs/PaymentDestinationInput" }, { "type": "null" } ], "default": null }, "requested_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Requested At" }, "evidence": { "anyOf": [ { "items": { "$ref": "#/$defs/EvidenceInput" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Evidence" }, "callback": { "anyOf": [ { "$ref": "#/$defs/CallbackInput" }, { "type": "null" } ], "default": null }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" } }, "required": [ "schema_version", "request_id", "policy_id", "supplier" ], "title": "verify_supplier_paymentArguments", "type": "object" }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.example.com/payment-verifier/verification-result.schema.json", "title": "VerificationResult", "type": "object", "additionalProperties": false, "required": [ "schema_version", "verification_id", "request_id", "status", "decision", "policy", "checks", "reason_codes", "billing", "created_at", "completed_at" ], "properties": { "schema_version": { "const": "1.0" }, "verification_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED" ] }, "decision": { "type": "string", "enum": [ "RELEASE", "REVIEW", "BLOCK", "INSUFFICIENT_EVIDENCE" ] }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "evidence_summary": { "type": "object" }, "advisory_only": { "const": true }, "policy": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" } } }, "checks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "outcome", "summary" ], "properties": { "code": { "type": "string" }, "outcome": { "type": "string", "enum": [ "PASS", "FAIL", "WARN", "UNAVAILABLE", "NOT_APPLICABLE" ] }, "summary": { "type": "string", "maxLength": 500 }, "evidence_ids": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } } }, "reason_codes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "required_actions": { "type": "array", "uniqueItems": true, "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "evidence_id", "source", "observed_at", "status" ], "properties": { "evidence_id": { "type": "string" }, "source": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "VERIFIED", "PARTIAL", "UNAVAILABLE", "CONTRADICTED" ] }, "reference": { "type": "string", "maxLength": 500 } } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "billable", "meter", "units" ], "properties": { "billable": { "type": "boolean" }, "meter": { "const": "verification.completed" }, "units": { "type": "integer", "minimum": 0, "maximum": 1 } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "trace_id": { "type": "string" } } } }, { "name": "get_verification", "description": "Retrieve a tenant-scoped completed verification.", "inputSchema": { "properties": { "verification_id": { "format": "uuid", "title": "Verification Id", "type": "string" } }, "required": [ "verification_id" ], "title": "get_verificationArguments", "type": "object" }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.example.com/payment-verifier/verification-result.schema.json", "title": "VerificationResult", "type": "object", "additionalProperties": false, "required": [ "schema_version", "verification_id", "request_id", "status", "decision", "policy", "checks", "reason_codes", "billing", "created_at", "completed_at" ], "properties": { "schema_version": { "const": "1.0" }, "verification_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED" ] }, "decision": { "type": "string", "enum": [ "RELEASE", "REVIEW", "BLOCK", "INSUFFICIENT_EVIDENCE" ] }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "evidence_summary": { "type": "object" }, "advisory_only": { "const": true }, "policy": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" } } }, "checks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "outcome", "summary" ], "properties": { "code": { "type": "string" }, "outcome": { "type": "string", "enum": [ "PASS", "FAIL", "WARN", "UNAVAILABLE", "NOT_APPLICABLE" ] }, "summary": { "type": "string", "maxLength": 500 }, "evidence_ids": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } } }, "reason_codes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "required_actions": { "type": "array", "uniqueItems": true, "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "evidence_id", "source", "observed_at", "status" ], "properties": { "evidence_id": { "type": "string" }, "source": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "VERIFIED", "PARTIAL", "UNAVAILABLE", "CONTRADICTED" ] }, "reference": { "type": "string", "maxLength": 500 } } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "billable", "meter", "units" ], "properties": { "billable": { "type": "boolean" }, "meter": { "const": "verification.completed" }, "units": { "type": "integer", "minimum": 0, "maximum": 1 } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "trace_id": { "type": "string" } } } } ] ## Versioned static synthetic fixtures and use-case scenarios SYNTHETIC_ILLUSTRATION: fictional inputs, placeholder signatures and unregistered keys; not live-valid requests. No fixture was executed, no gates evaluated and no payments authorized. { "schema_version": "1.0", "reviewed_at": "2026-10-16", "label": "SYNTHETIC_ILLUSTRATION", "warning": "Offline illustrations only: no live checks, signature verification, key registration or payments were performed. Fictional supplier names, CRO 000000, VAT IE0000000A and SYNTHETIC document IDs are not registry claims. The IBAN is a public test-format example, not a payment destination. Signature and public-key placeholders make these NOT live-valid requests. Assumed outcomes are not current observations, signed receipts, attestations or payment authorization.", "live_checks_performed": false, "payment_made": false, "invoice_money_moved": false, "guide": "/use-cases/supplier-invoice-verification", "request_schema": "/schemas/decision.schema.json", "contract": "Illustrative assumptions and decisions, deliberately NOT an executed DecisionPayload response.", "operation_examples": [ { "label": "SYNTHETIC_ILLUSTRATION", "operation": "check_iban", "title": "Validate an IBAN", "price_usdc": "0.005", "input_schema": "/schemas/iban.schema.json", "rest": { "method": "POST", "path": "/v1/checks/iban", "body": { "iban": "IE29AIBK93115212345678" } }, "mcp": { "name": "check_iban", "arguments": { "request": { "iban": "IE29AIBK93115212345678" } } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "check_iban", "request": { "iban": "IE29AIBK93115212345678" } } } ] } } } }, { "label": "SYNTHETIC_ILLUSTRATION", "operation": "check_vat", "title": "Check an Irish VAT number", "price_usdc": "0.01", "input_schema": "/schemas/vat.schema.json", "rest": { "method": "POST", "path": "/v1/checks/vat", "body": { "vat_number": "IE0000000A" } }, "mcp": { "name": "check_vat", "arguments": { "request": { "vat_number": "IE0000000A" } } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "check_vat", "request": { "vat_number": "IE0000000A" } } } ] } } } }, { "label": "SYNTHETIC_ILLUSTRATION", "operation": "check_company", "title": "Check an Irish company status (CRO)", "price_usdc": "0.01", "input_schema": "/schemas/company.schema.json", "rest": { "method": "POST", "path": "/v1/checks/company", "body": { "cro_number": "000000" } }, "mcp": { "name": "check_company", "arguments": { "request": { "cro_number": "000000" } } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "check_company", "request": { "cro_number": "000000" } } } ] } } } }, { "label": "SYNTHETIC_ILLUSTRATION", "operation": "check_three_way_match", "title": "3-way match PO, goods receipt and invoice", "price_usdc": "0.02", "input_schema": "/schemas/three_way.schema.json", "rest": { "method": "POST", "path": "/v1/checks/three-way-match", "body": { "supplier_cro_number": "000000", "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] } } }, "mcp": { "name": "check_three_way_match", "arguments": { "request": { "supplier_cro_number": "000000", "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] } } } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "check_three_way_match", "request": { "supplier_cro_number": "000000", "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] } } } } ] } } } }, { "label": "SYNTHETIC_ILLUSTRATION", "operation": "decide_supplier_payment", "title": "Decide: pay this supplier invoice or not", "price_usdc": "0.05", "input_schema": "/schemas/decision.schema.json", "rest": { "method": "POST", "path": "/v1/payment-decisions", "body": { "transaction_id": "SYNTHETIC-OFFLINE-ONLY", "supplier": { "cro_number": "000000", "vat_number": "IE0000000A", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] }, "signature": { "key_id": "SYNTHETIC-UNREGISTERED", "signature_b64": "OFFLINE_PLACEHOLDER_NOT_A_SIGNATURE" } } }, "mcp": { "name": "decide_supplier_payment", "arguments": { "payment_request": { "transaction_id": "SYNTHETIC-OFFLINE-ONLY", "supplier": { "cro_number": "000000", "vat_number": "IE0000000A", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] }, "signature": { "key_id": "SYNTHETIC-UNREGISTERED", "signature_b64": "OFFLINE_PLACEHOLDER_NOT_A_SIGNATURE" } } } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "decide_supplier_payment", "request": { "transaction_id": "SYNTHETIC-OFFLINE-ONLY", "supplier": { "cro_number": "000000", "vat_number": "IE0000000A", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "SYNTHETIC-PO", "grn_number": "SYNTHETIC-GRN", "invoice_number": "SYNTHETIC-INVOICE", "amount": "100.00", "currency": "EUR", "payee_name": "Fictional Synthetic Widget Supplier DAC", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "purchase_order": { "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "amount": "100.00", "currency": "EUR", "line_items": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1", "unit_price": "100.00" } ] }, "goods_receipt": { "grn_number": "SYNTHETIC-GRN", "po_number": "SYNTHETIC-PO", "supplier_cro_number": "000000", "received": [ { "sku": "SYNTHETIC-WIDGET", "quantity": "1" } ] }, "signature": { "key_id": "SYNTHETIC-UNREGISTERED", "signature_b64": "OFFLINE_PLACEHOLDER_NOT_A_SIGNATURE" } } } } ] } } } }, { "label": "SYNTHETIC_ILLUSTRATION", "operation": "register_signing_key", "title": "Register a signing key", "price_usdc": "0.005", "input_schema": "/schemas/keys.schema.json", "rest": { "method": "POST", "path": "/v1/agent-keys", "body": { "key_id": "SYNTHETIC-UNREGISTERED", "public_key_pem": "OFFLINE_PLACEHOLDER_NOT_A_PUBLIC_KEY" } }, "mcp": { "name": "register_signing_key", "arguments": { "key_id": "SYNTHETIC-UNREGISTERED", "public_key_pem": "OFFLINE_PLACEHOLDER_NOT_A_PUBLIC_KEY" } }, "a2a": { "jsonrpc": "2.0", "id": "SYNTHETIC-RPC", "method": "message/send", "params": { "message": { "kind": "message", "messageId": "SYNTHETIC-MESSAGE", "role": "user", "parts": [ { "kind": "data", "data": { "operation": "register_signing_key", "request": { "key_id": "SYNTHETIC-UNREGISTERED", "public_key_pem": "OFFLINE_PLACEHOLDER_NOT_A_PUBLIC_KEY" } } } ] } } } } ], "scenarios": [ { "id": "all-five-pass", "label": "SYNTHETIC_ILLUSTRATION", "live_checks_performed": false, "payment_made": false, "invoice_money_moved": false, "assumed_check_outcomes": { "CRO": "PASSED", "VIES_VAT": "PASSED", "CONFIRMATION_OF_PAYEE": "PASSED", "ERP_THREE_WAY_MATCH": "PASSED", "A2A_SIGNATURE": "PASSED" }, "assumed_policy_flags": [], "illustrative_decision": "EXECUTE_PAYMENT", "illustrative_reason_codes": [], "explanation": "Assume all five gates pass, EUR amount within policy limit, unchanged IBAN, supplier master available and no graph or other flags. Rule pass only, not a guarantee of safe payment." }, { "id": "bad-signature", "label": "SYNTHETIC_ILLUSTRATION", "live_checks_performed": false, "payment_made": false, "invoice_money_moved": false, "assumed_check_outcomes": { "CRO": "UNAVAILABLE", "VIES_VAT": "UNAVAILABLE", "CONFIRMATION_OF_PAYEE": "UNAVAILABLE", "ERP_THREE_WAY_MATCH": "UNAVAILABLE", "A2A_SIGNATURE": "FAILED" }, "assumed_policy_flags": [], "illustrative_decision": "REJECT_PAYMENT", "illustrative_reason_codes": [ "SIGNATURE_INVALID" ], "explanation": "Assume signature failure. Other gates are skipped and represented as UNAVAILABLE; no outbound registry checks are implied. Signature failure takes precedence over review." }, { "id": "provider-unavailable", "label": "SYNTHETIC_ILLUSTRATION", "live_checks_performed": false, "payment_made": false, "invoice_money_moved": false, "assumed_check_outcomes": { "CRO": "PASSED", "VIES_VAT": "UNAVAILABLE", "CONFIRMATION_OF_PAYEE": "PASSED", "ERP_THREE_WAY_MATCH": "PASSED", "A2A_SIGNATURE": "PASSED" }, "assumed_policy_flags": [], "illustrative_decision": "FLAG_FOR_HUMAN_REVIEW", "illustrative_reason_codes": [ "VIES_UNAVAILABLE" ], "explanation": "Assume VIES is unavailable and the other four gates pass, with no other flags. Provider uncertainty requires human review, never execute." } ] } ## Current OpenAPI JSON Literal application.openapi() output, including all registered public contracts, constraints, response models and configured public authentication/payment metadata: { "openapi": "3.1.0", "info": { "title": "Trusted Supplier Payment Verifier API", "description": "Advisory verification API. It does not execute payments.", "version": "0.1.0" }, "paths": { "/v1/verifications": { "post": { "summary": "Create Verification", "operationId": "createVerification", "security": [ { "x402": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 200, "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "Payload", "$ref": "../schemas/verification-request.schema.json" } } } }, "responses": { "201": { "description": "Verification completed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Createverification", "$ref": "../schemas/verification-result.schema.json" } } } }, "200": { "description": "Existing terminal result for the same idempotent request", "content": { "application/json": { "schema": { "$ref": "../schemas/verification-result.schema.json" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Unauthorised" }, "409": { "description": "Idempotency conflict" }, "422": { "description": "Semantically invalid request" }, "429": { "description": "Rate limit exceeded" }, "503": { "description": "Verification service unavailable" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." } } } }, "/v1/verifications/{verification_id}": { "get": { "summary": "Get Verification", "operationId": "getVerification", "security": [ { "x402": [] } ], "parameters": [ { "name": "verification_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Verification Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Getverification" } } } }, "404": { "description": "Not found in authenticated tenant" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." } } } }, "/v1/checks/iban": { "post": { "summary": "Validate an IBAN", "description": "Cheapest call. Validates an IBAN (ISO 13616 mod-97 checksum, length and country) before you pay it. Returns PASSED or FAILED with a reason code. Irish (IE) IBANs pass by default.", "operationId": "check_iban", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "iban": { "description": "IBAN to validate (spaces allowed).", "maxLength": 40, "minLength": 5, "title": "Iban", "type": "string" } }, "required": [ "iban" ], "title": "IbanCheckRequest", "type": "object" }, "examples": { "request": { "value": { "iban": "IE29AIBK93115212345678" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Check Iban" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.005" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "iban_validation", "payment_verification" ] } }, "/v1/checks/vat": { "post": { "summary": "Check an Irish VAT number", "description": "Validates the Irish VAT number format and check letter, then confirms registration live with EU VIES. Returns PASSED, FAILED or UNAVAILABLE (VIES outage) with a reason code.", "operationId": "check_vat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "vat_number": { "description": "Irish VAT number, with or without the IE prefix.", "maxLength": 20, "minLength": 2, "title": "Vat Number", "type": "string" } }, "required": [ "vat_number" ], "title": "VatCheckRequest", "type": "object" }, "examples": { "request": { "value": { "vat_number": "IE6388047V" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Check Vat" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.01" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "vat_validation", "supplier_verification" ] } }, "/v1/checks/company": { "post": { "summary": "Check an Irish company status (CRO)", "description": "Looks up an Irish company by CRO number in the Companies Registration Office open data. PASSED only if the company status is NORMAL; dissolved, liquidated or unknown companies FAIL. Returns the registered name.", "operationId": "check_company", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cro_number": { "description": "Irish CRO company number.", "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" } }, "required": [ "cro_number" ], "title": "CompanyCheckRequest", "type": "object" }, "examples": { "request": { "value": { "cro_number": "123456" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Check Company" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.01" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "company_verification", "kyb" ] } }, "/v1/checks/three-way-match": { "post": { "summary": "3-way match PO, goods receipt and invoice", "description": "Checks that a purchase order, goods receipt and invoice agree on supplier, currency, amount, line items, unit prices and quantities received. Stateless; you attach the documents. Checks caller-supplied documents, not independently verified ERP records.", "operationId": "check_three_way_match", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "supplier_cro_number": { "maxLength": 16, "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "purchase_order": { "$ref": "#/components/schemas/PurchaseOrder" }, "goods_receipt": { "$ref": "#/components/schemas/GoodsReceipt" } }, "required": [ "supplier_cro_number", "invoice", "purchase_order", "goods_receipt" ], "title": "ThreeWayMatchRequest", "type": "object" }, "examples": { "request": { "value": { "supplier_cro_number": "123456", "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Check Three Way Match" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.02" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "three_way_match", "accounts_payable" ] } }, "/v1/payment-decisions": { "post": { "summary": "Decide: pay this supplier invoice or not", "description": "Flagship. Independent third-party decision for an Irish supplier invoice. Runs five gates (CRO status NORMAL, EU VIES VAT, payee-name and IBAN check, PO/GRN/invoice 3-way match, RSA signature) and returns exactly one of EXECUTE_PAYMENT, REJECT_PAYMENT or FLAG_FOR_HUMAN_REVIEW with per-check results, reason codes and a confidence score. The legacy CONFIRMATION_OF_PAYEE result means a payee-name comparison with the CRO legal name and IBAN validation, not bank Confirmation of Payee. ERP_THREE_WAY_MATCH compares caller-supplied documents, not independently verified ERP records. Decides only; never moves money. Register a signing key first via /v1/agent-keys.", "operationId": "decide_supplier_payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "transaction_id": { "maxLength": 64, "minLength": 1, "title": "Transaction Id", "type": "string" }, "supplier": { "$ref": "#/components/schemas/Supplier" }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "purchase_order": { "$ref": "#/components/schemas/PurchaseOrder" }, "goods_receipt": { "$ref": "#/components/schemas/GoodsReceipt" }, "signature": { "$ref": "#/components/schemas/SignatureEnvelope" } }, "required": [ "transaction_id", "supplier", "invoice", "purchase_order", "goods_receipt", "signature" ], "title": "PaymentRequest", "type": "object" }, "examples": { "request": { "value": { "transaction_id": "inv-2026-0042", "supplier": { "cro_number": "123456", "vat_number": "IE6388047V", "iban": "IE29AIBK93115212345678" }, "invoice": { "po_number": "PO-1", "grn_number": "GRN-1", "invoice_number": "INV-1", "amount": "1000.00", "currency": "EUR", "payee_name": "Example Supplier Designated Activity Company", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "purchase_order": { "po_number": "PO-1", "supplier_cro_number": "123456", "amount": "1000.00", "currency": "EUR", "line_items": [ { "sku": "A", "quantity": "1", "unit_price": "1000.00" } ] }, "goods_receipt": { "grn_number": "GRN-1", "po_number": "PO-1", "supplier_cro_number": "123456", "received": [ { "sku": "A", "quantity": "1" } ] }, "signature": { "key_id": "my-key-1", "signature_b64": "" } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Decide Supplier Payment" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.05" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "payment_decision", "accounts_payable", "fraud_prevention" ] } }, "/v1/agent-keys": { "post": { "summary": "Register a signing key", "description": "Registers an RSA public key (2048-bit or larger, PEM) used to sign payment-decision requests. Keys are immutable per tenant; rotate by registering a new key_id.", "operationId": "register_signing_key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "key_id": { "maxLength": 128, "minLength": 1, "title": "Key Id", "type": "string" }, "public_key_pem": { "maxLength": 16384, "minLength": 1, "title": "Public Key Pem", "type": "string" } }, "required": [ "key_id", "public_key_pem" ], "title": "SigningKeyRequest", "type": "object" }, "examples": { "request": { "value": { "key_id": "my-key-1", "public_key_pem": "-----BEGIN PUBLIC KEY-----..." } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Register Signing Key" } } } }, "400": { "description": "Invalid request" }, "402": { "description": "Payment required. x402 requirements are in the PAYMENT-REQUIRED header and JSON body." }, "409": { "description": "Conflicts with an earlier request" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "x402": [] } ], "x-payment-info": { "price": { "currency": "USD", "mode": "fixed", "amount": "0.005" }, "protocols": [ { "x402": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0395c1bed0b83ad6f0329b4132191934733e637c", "maxTimeoutSeconds": 60 } } ] }, "x-intents": [ "key_registration" ] } }, "/v1/stats/payers": { "get": { "tags": [ "stats" ], "summary": "Agents that have paid us (anonymised, free)", "description": "Social proof: settled payments only; wallet addresses are truncated.", "operationId": "payingAgents", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Payingagents" } } } } } } }, "/demo": { "get": { "tags": [ "discovery" ], "summary": "Synthetic example only; no live checks or payments", "operationId": "demo_demo_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Demo Demo Get" } } } } } } }, "/integrations/vscode-mcp.json": { "get": { "tags": [ "discovery" ], "summary": "Vscode Config", "operationId": "vscode_config_integrations_vscode_mcp_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/integrations/cursor-mcp.json": { "get": { "tags": [ "discovery" ], "summary": "Cursor Config", "operationId": "cursor_config_integrations_cursor_mcp_json_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/llms-full.txt": { "get": { "tags": [ "discovery" ], "summary": "Handbook", "operationId": "handbook_llms_full_txt_get", "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "GoodsReceipt": { "additionalProperties": false, "properties": { "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "received": { "items": { "$ref": "#/components/schemas/ReceivedLine" }, "minItems": 1, "title": "Received", "type": "array" } }, "required": [ "grn_number", "po_number", "supplier_cro_number", "received" ], "title": "GoodsReceipt", "type": "object" }, "Invoice": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "grn_number": { "minLength": 1, "title": "Grn Number", "type": "string" }, "invoice_number": { "minLength": 1, "title": "Invoice Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/components/schemas/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" }, "payee_name": { "maxLength": 300, "minLength": 1, "title": "Payee Name", "type": "string" } }, "required": [ "po_number", "grn_number", "invoice_number", "amount", "currency", "line_items", "payee_name" ], "title": "Invoice", "type": "object" }, "LineItem": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" }, "unit_price": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Unit Price" } }, "required": [ "sku", "quantity", "unit_price" ], "title": "LineItem", "type": "object" }, "PurchaseOrder": { "additionalProperties": false, "properties": { "po_number": { "minLength": 1, "title": "Po Number", "type": "string" }, "supplier_cro_number": { "minLength": 1, "title": "Supplier Cro Number", "type": "string" }, "amount": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "currency": { "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "line_items": { "items": { "$ref": "#/components/schemas/LineItem" }, "minItems": 1, "title": "Line Items", "type": "array" } }, "required": [ "po_number", "supplier_cro_number", "amount", "currency", "line_items" ], "title": "PurchaseOrder", "type": "object" }, "ReceivedLine": { "additionalProperties": false, "properties": { "sku": { "minLength": 1, "title": "Sku", "type": "string" }, "quantity": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Quantity" } }, "required": [ "sku", "quantity" ], "title": "ReceivedLine", "type": "object" }, "SignatureEnvelope": { "additionalProperties": false, "description": "RSA signature over the canonical JSON of the request body, plus mTLS evidence.", "properties": { "key_id": { "minLength": 1, "title": "Key Id", "type": "string" }, "signature_b64": { "minLength": 1, "title": "Signature B64", "type": "string" }, "mtls_cert_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mtls Cert Fingerprint" } }, "required": [ "key_id", "signature_b64" ], "title": "SignatureEnvelope", "type": "object" }, "Supplier": { "additionalProperties": false, "properties": { "cro_number": { "maxLength": 16, "minLength": 1, "title": "Cro Number", "type": "string" }, "vat_number": { "maxLength": 20, "minLength": 1, "title": "Vat Number", "type": "string" }, "iban": { "maxLength": 40, "minLength": 1, "title": "Iban", "type": "string" } }, "required": [ "cro_number", "vat_number", "iban" ], "title": "Supplier", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" }, "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 v2 alternative to bearer auth. First call without payment to receive HTTP 402 and PAYMENT-REQUIRED; use a wallet-enabled x402 client to sign and retry. No account or bearer token is required when paying." } } } }