Skip to content

NetFabric/intelligentium / plugins/ucp/.apm/skills/ucp-platform-integration

ucp-platform-integration

Verified

Consume the Universal Commerce Protocol (UCP) as a platform, app, or AI agent: discover business capabilities via /.well-known/ucp, negotiate protocol/capability versions, send the UCP-Agent header, drive the checkout session lifecycle (create/get/update/complete/cancel), process status/messages/continue_url handoff, acquire and submit payment instruments (digital wallets, tokenization, AP2 mandates), sign requests (RFC 9421), and call UCP over REST, MCP, A2A, or Embedded transports. USE FOR: building an AI shopping agent, app, or procurement system that discovers and transacts with UCP businesses; capability negotiation and version-matching logic; checkout status/error handling; payment handler execution; choosing between REST/MCP/A2A/Embedded bindings. DO NOT USE FOR: implementing a UCP business/merchant server (see ucp-business-integration); generic MCP or A2A protocol usage unrelated to commerce; non-UCP payment processing.

UCP Platform Integration

UCP lets a platform (AI shopping agent, app, procurement system) discover any business's checkout/cart/order capabilities from one machine-readable profile and transact — no bespoke integration per business.

Anatomy

FilePurpose
SKILL.mdRoles, negotiation flow, checkout quick-reference
references/discovery-and-negotiation.mdFetching profiles, capability intersection, namespace validation, schema resolution
references/checkout-flow.mdOperations, status lifecycle, error processing, totals, continue_url
references/payments-execution.mdAcquiring/submitting payment instruments, the 3 handler scenarios, signing requests
references/transports-mcp-a2a.mdREST vs MCP vs A2A vs Embedded request/response shapes

Roles

RoleNotes
Platform (you)App/AI agent consuming capabilities on behalf of a user or process
BusinessMerchant of Record; publishes the profile you discover
Credential Provider (CP)Wallet/identity provider (Google Pay, Shop Pay) you talk to directly for tokens
PSPPayment processor the business charges through; you never talk to it directly

Discovery & Negotiation Flow

  1. Fetch the business profile: GET https://business.example.com/.well-known/ucp.
  2. Match your protocol version to its version (or a key in supported_versions); stop if neither matches.
  3. Validate each capability's schema URL origin against its reverse-domain namespace before trusting it.
  4. Advertise your own profile URL on every request via UCP-Agent (REST) or meta.ucp-agent.profile (MCP).
  5. Read ucp.capabilities in every response — it tells you exactly what's active for that operation.

UCP-Agent Header

# REST (RFC 8941 Dictionary syntax)
UCP-Agent: profile="https://agent.example/profile"
// MCP — inside params.arguments
{ "meta": { "ucp-agent": { "profile": "https://agent.example/profile" } } }

Checkout Operations

OperationMethod & PathCall it when
Create CheckoutPOST /checkout-sessionsUser expresses purchase intent
Get CheckoutGET /checkout-sessions/{id}Resuming/polling session state
Update CheckoutPUT /checkout-sessions/{id}Fixing a recoverable error or adding info (full replacement)
Complete CheckoutPOST /checkout-sessions/{id}/completeBuyer commits to pay; returns the placed order
Cancel CheckoutPOST /checkout-sessions/{id}/cancelAbandoning a non-terminal session

Workflow: Building a UCP Client

  1. Discover and negotiate: fetch the profile, validate namespaces, pick a transport.
  2. Create Checkout when the user expresses purchase intent.
  3. Run the error-processing algorithm on messages; call Update to fix recoverable issues.
  4. Acquire a payment instrument via the negotiated handler, then call Complete.
  5. Hand off to continue_url whenever status is requires_escalation (or any other handoff case).

Reference Files

FileLoad When
references/discovery-and-negotiation.mdFetching/caching profiles, validating schema namespaces, handling discovery errors
references/checkout-flow.mdImplementing the checkout state machine, error handling, or totals rendering
references/payments-execution.mdAcquiring payment tokens/mandates or signing requests
references/transports-mcp-a2a.mdChoosing or implementing REST, MCP, A2A, or Embedded transport bindings
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall