NetFabric/intelligentium / plugins/ucp/.apm/skills/ucp-platform-integration
ucp-platform-integration
VerifiedConsume 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
| File | Purpose |
|---|---|
| SKILL.md | Roles, negotiation flow, checkout quick-reference |
| references/discovery-and-negotiation.md | Fetching profiles, capability intersection, namespace validation, schema resolution |
| references/checkout-flow.md | Operations, status lifecycle, error processing, totals, continue_url |
| references/payments-execution.md | Acquiring/submitting payment instruments, the 3 handler scenarios, signing requests |
| references/transports-mcp-a2a.md | REST vs MCP vs A2A vs Embedded request/response shapes |
Roles
| Role | Notes |
|---|---|
| Platform (you) | App/AI agent consuming capabilities on behalf of a user or process |
| Business | Merchant of Record; publishes the profile you discover |
| Credential Provider (CP) | Wallet/identity provider (Google Pay, Shop Pay) you talk to directly for tokens |
| PSP | Payment processor the business charges through; you never talk to it directly |
Discovery & Negotiation Flow
- Fetch the business profile:
GET https://business.example.com/.well-known/ucp. - Match your protocol version to its
version(or a key insupported_versions); stop if neither matches. - Validate each capability's
schemaURL origin against its reverse-domain namespace before trusting it. - Advertise your own profile URL on every request via
UCP-Agent(REST) ormeta.ucp-agent.profile(MCP). - Read
ucp.capabilitiesin 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
| Operation | Method & Path | Call it when |
|---|---|---|
| Create Checkout | POST /checkout-sessions | User expresses purchase intent |
| Get Checkout | GET /checkout-sessions/{id} | Resuming/polling session state |
| Update Checkout | PUT /checkout-sessions/{id} | Fixing a recoverable error or adding info (full replacement) |
| Complete Checkout | POST /checkout-sessions/{id}/complete | Buyer commits to pay; returns the placed order |
| Cancel Checkout | POST /checkout-sessions/{id}/cancel | Abandoning a non-terminal session |
Workflow: Building a UCP Client
- Discover and negotiate: fetch the profile, validate namespaces, pick a transport.
- Create Checkout when the user expresses purchase intent.
- Run the error-processing algorithm on
messages; call Update to fixrecoverableissues. - Acquire a payment instrument via the negotiated handler, then call Complete.
- Hand off to
continue_urlwhenever status isrequires_escalation(or any other handoff case).
Reference Files
| File | Load When |
|---|---|
| references/discovery-and-negotiation.md | Fetching/caching profiles, validating schema namespaces, handling discovery errors |
| references/checkout-flow.md | Implementing the checkout state machine, error handling, or totals rendering |
| references/payments-execution.md | Acquiring payment tokens/mandates or signing requests |
| references/transports-mcp-a2a.md | Choosing or implementing REST, MCP, A2A, or Embedded transport bindings |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 468k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |