Complete public handbook with full schemas · VS Code configuration download · Cursor configuration download. An operator must review and merge entries into existing configuration, not overwrite it. Downloads never connect, auto-install, register keys or pay. Configuration trust approval is not payment approval. All supplier-operation MCP tools are paid; synthetic demos are HTTP/offline-client only.

Supplier invoice verification for bot builders

Use an advisory check before your accounts-payable bot recommends a supplier invoice for approval. This service never transfers invoice money. Keep customer-controlled payment approval and independent account-ownership controls. Reviewed 2026-10-16; this date is a documentation review, not a verification timestamp.

Choose the smallest useful operation

IBAN only: catch formatting, country and checksum errors before collecting more evidence. A pass does not identify the account owner.
VAT only: validate Irish VAT format/check letter, then check EU VIES registration. UNAVAILABLE means uncertainty, not invalid registration.
CRO only: check Irish company status; NORMAL is the passing status. It is not proof of invoice authenticity.
Three-way match: compare supplied invoice, purchase order and goods receipt, without ERP access.
Full signed decision: register an RSA public key first, then submit the signed invoice, PO and goods receipt when you need all five gates and the combined advisory policy.

Use case	REST / MCP operation	Service fee	Contract
Validate an IBAN	`POST /v1/checks/iban` `check_iban`	0.005 USDC	Input schema
Check an Irish VAT number	`POST /v1/checks/vat` `check_vat`	0.01 USDC	Input schema
Check an Irish company status (CRO)	`POST /v1/checks/company` `check_company`	0.01 USDC	Input schema
3-way match PO, goods receipt and invoice	`POST /v1/checks/three-way-match` `check_three_way_match`	0.02 USDC	Input schema
Decide: pay this supplier invoice or not	`POST /v1/payment-decisions` `decide_supplier_payment`	0.05 USDC	Input schema
Register a signing key	`POST /v1/agent-keys` `register_signing_key`	0.005 USDC	Input schema

Interpret the five-gate decision, not a payment instruction

The gates are CRO, VIES_VAT, CONFIRMATION_OF_PAYEE, ERP_THREE_WAY_MATCH and A2A_SIGNATURE. The legacy label CONFIRMATION_OF_PAYEE means payee-name comparison with the CRO legal name plus IBAN validation, not bank Confirmation of Payee or bank-account ownership. ERP_THREE_WAY_MATCH compares caller-supplied documents, not authenticated ERP records. A valid signature identifies the signer of supplied data, not its business truth.

EXECUTE_PAYMENT: all five pass and no policy or graph flags; confidence 1.0 means rule pass, not certainty of safety or a financial guarantee.
REJECT_PAYMENT: a failed signature, failed VAT or failed CRO gate. Bad signatures skip outbound checks.
FLAG_FOR_HUMAN_REVIEW: provider unavailable, name/document mismatch, changed or shared identifiers, supplier-master uncertainty, or amount/currency policy flags. Retain human approval.

The legacy POST /v1/verifications workflow is separate: its four outcomes are RELEASE, REVIEW, BLOCK, INSUFFICIENT_EVIDENCE. Do not map its results to the five-gate contract by name alone.

Offline scenarios, not verified supplier examples

Version 1.0 machine-readable fixtures illustrate all-five-pass → EXECUTE_PAYMENT with no flags; bad-signature → REJECT_PAYMENT without outbound checks; and provider-unavailable → FLAG_FOR_HUMAN_REVIEW. These are explicit assumptions, not executed checks. Placeholder CRO/VAT records cannot demonstrate a live pass. There are no fabricated audit receipts or attestations.

Use the right transport shape

REST bodies are flat objects matching the linked input schemas. MCP check tools wrap that same body in arguments.request; decide_supplier_payment uses arguments.payment_request; register_signing_key stays flat with key_id/public_key_pem. Inspect tools/list at /mcp/ for runtime contracts. MCP connectivity alone cannot pay.

A2A uses the JSON-RPC 0.3 binding (JSON-RPC envelope "jsonrpc":"2.0"), not A2A 1.0. POST /a2a, method message/send, one data part containing {"operation":"check_iban","request":{"iban":"IE29AIBK93115212345678"}}. Select catalog operation names, including register_signing_key then decide_supplier_payment; request is always the same flat REST body, not an MCP wrapper. Full envelopes for every operation are in the offline JSON fixtures.

Sign normalized requests and cap service fees

Use the public client's PaymentRequest.model_validate() and PaymentRequest.signed_body() canonicalizer (also described by the decision input schema). Normalize Decimal fields before sorted-key, compact JSON serialization excluding signature. Sign using RSA-PSS, SHA-256, MGF1(SHA-256), digest-length salt. Do not sign raw unnormalized JSON. Only register public keys; never publish private keys or wallet credentials.

x402 requires a wallet and a payment-capable client. Registration costs 0.005 USDC and a decision costs 0.05 USDC: 0.055 USDC combined service fees, not invoice payment. Validate quoted scheme, network, USDC asset and remaining budget. Base mainnet fees spend real USDC. Recreating the ephemeral signing key can incur registration again.

Standalone client and optional framework tools

Use the standalone PyPI package; no backend checkout is needed: public buyer client and offline examples.

python -m pip install supplier-payment-assistant
supplier-payment-assistant --demo
# Offline demo; no wallet, model calls or paid checks.
supplier-payment-assistant https://supplier-payment-verifier-production.up.railway.app --request .\invoice.json
# Inspection only; no payment authorization.
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()

The SupplierPaymentTools factory defaults to offline_demo and inspect_supplier, with no paid tool. An operator-defined approval_policy must compare the exact validated canonical request digest against a trusted approved record; model assertions or model-supplied digests cannot authorize spend. The model must not control wallet, URL or budget settings. Retain one session instance: default one paid attempt and 0.055 USDC cumulative reservations; failures retain reservations. Budgets are in-memory, not durable, and reset on recreation/restart. Production requires external durable approval and budget controls. No silent autopay or automatic paid retries. Missing settlement metadata is unconfirmed and stops the flow; a paid review decision is still a billable advisory result.

Privacy and production handoff

Obtain operator authorization before sending invoice data or results to an LLM or tracing provider; configure redaction, retention and access controls. Never include credentials in prompts, traces or public examples. Keep payment execution outside these tools and require customer approval before bank submission. See the buyer quickstart for explicit paid-mode controls, OpenAPI for response contracts and the A2A card for discovery.