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.

---
name: ucp-platform-integration
description: "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

| File | Purpose |
|------|---------|
| SKILL.md | Roles, negotiation flow, checkout quick-reference |
| [references/discovery-and-negotiation.md](references/discovery-and-negotiation.md) | Fetching profiles, capability intersection, namespace validation, schema resolution |
| [references/checkout-flow.md](references/checkout-flow.md) | Operations, status lifecycle, error processing, totals, continue_url |
| [references/payments-execution.md](references/payments-execution.md) | Acquiring/submitting payment instruments, the 3 handler scenarios, signing requests |
| [references/transports-mcp-a2a.md](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

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

```http
# REST (RFC 8941 Dictionary syntax)
UCP-Agent: profile="https://agent.example/profile"
```
```json
// 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

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

| File | Load When |
|------|-----------|
| [references/discovery-and-negotiation.md](references/discovery-and-negotiation.md) | Fetching/caching profiles, validating schema namespaces, handling discovery errors |
| [references/checkout-flow.md](references/checkout-flow.md) | Implementing the checkout state machine, error handling, or totals rendering |
| [references/payments-execution.md](references/payments-execution.md) | Acquiring payment tokens/mandates or signing requests |
| [references/transports-mcp-a2a.md](references/transports-mcp-a2a.md) | Choosing 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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall