Glossary

Glossary

Term	Definition
ACP	Agentic Commerce Protocol — Stripe + OpenAI's spec for agent-driven commerce. Per-session capability negotiation, mandatory Bearer auth. See UCP and ACP.
Adapter	An instance of a class implementing PaymentHandlerAdapter. Created by the handler's Medusa module at boot, dispatched by id.
agentic_commerce_api_key	The Bearer token agents must supply on /acp/* requests. Sourced from the api_key plugin option (AGENTIC_COMMERCE_API_KEY env var by convention).
agenticCommerce (module)	The core Medusa module exported by @financedistrict/medusa-plugin-agentic-commerce. Holds plugin config, the handler registry, and the protocol-formatting service.
CAIP-2	Chain Agnostic Improvement Proposal 2 — chain identifier format used by x402 (e.g. eip155:84532 for Base Sepolia).
Discovery	The act of an agent learning what a storefront supports. UCP: static /.well-known/ucp. ACP: per-session in CheckoutSession response.
EIP-3009	Ethereum Improvement Proposal — transferWithAuthorization for ERC-20s. Underlies Prism's signed-credential flow.
handlerId	Reverse-DNS identifier for a handler type, e.g. xyz.fd.prism_payment. Stable per-version.
Handler	Generic term for a payment handler — could mean the package, the class, or the instance depending on context.
Handler registry	The runtime list of payment-handler adapters resolved from the Medusa container at boot. Configured via payment_handler_adapters: ["..."] on the agenticCommerce module options.
JSON Schema Draft 2020-12	The schema dialect both UCP and ACP use for handler config validation.
Module (Medusa)	A unit of code with its own DI container, lifecycle, and isolation boundary in Medusa v2. Each handler ships as a Medusa module.
OpenAPI	API description format. ACP ships an OpenAPI doc at spec/<version>/openapi/.
payment_handler_adapters	Plugin option — array of Medusa module keys (strings) the agenticCommerce service should load as payment handlers.
Payment provider (Medusa)	Distinct from a handler adapter. Implements AbstractPaymentProvider for Medusa's standard authorize/capture/refund. The Prism package ships both a handler adapter AND a payment provider; some handlers may ship only one.
PaymentHandlerAdapter	TypeScript interface every payment handler class must implement. Defines discovery, prepare, response-formatting methods.
Plugin (Medusa)	A higher-level Medusa concept than a module — auto-registers routes, workflows, subscribers, scheduled jobs. The agentic commerce package is both a plugin (for routes/lifecycle) and a module (for the core service).
PSP	Payment Service Provider. Required field in ACP PaymentHandler (e.g. psp: "stripe", psp: "prism").
Reverse-DNS	Naming convention xyz.fd.foo (matches your domain reversed). Used for handler identifiers, capability namespaces, etc.
UCP	Universal Commerce Protocol — open spec for agent commerce. REST-style with a static well-known discovery doc. See UCP and ACP.
x402	Stablecoin payment scheme used by Prism. Built on EIP-3009.