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.

references/payments-execution.md

View on GitHub
# Payment Execution

## The 3-Step Lifecycle

1. **Negotiation** — read `payment_handlers` from the business's checkout response (already filtered to this cart's context).
2. **Acquisition** — execute the handler's own protocol directly against its Credential Provider (never through the business) to obtain an opaque token, encrypted payload, or mandate.
3. **Completion** — submit the resulting instrument via Complete Checkout; the business charges it through its own PSP integration.

## Scenario A — Digital Wallet (Google Pay / Shop Pay)

Read the handler's `config` (`merchant_info`, `allowed_payment_methods`, `tokenization_specification`, or `shop_id`) from the checkout response, call the wallet's own SDK/API with it to get an encrypted token, then wrap it as a `payment.instruments[]` entry:

```json
{ "payment": { "instruments": [{
  "id": "pm_1234567890abc", "handler_id": "8c9202bd-...", "type": "card", "selected": true,
  "display": { "brand": "visa", "last_digits": "4242" },
  "credential": { "type": "PAYMENT_GATEWAY", "token": "{\"signature\":\"...\"}" }
}] } }
```

## Scenario B — Direct Tokenization + SCA Challenge

Call the tokenizer's `token_url` with its `public_key` to mint a token, then submit it at Complete. If the PSP soft-declines, the business responds `status: "requires_escalation"` with `code: "requires_3ds"` and a `continue_url` challenge page — open it (WebView/window), then retry Complete once the buyer finishes the bank challenge.

## Scenario C — Autonomous Agent (AP2 Mandates)

For a `dev.ucp.shopping.ap2_mandate`-compatible handler, instead of a bare token you cryptographically sign:

- A **CheckoutMandate** — the hash of the offered `CheckoutObject` (proves you saw and agreed to these exact terms).
- A **PaymentMandate** — an SD-JWT-VC payment authorization signed with the user's credential.

Submit both at Complete Checkout (`payment.instruments[].credential` + the request's `ap2` block). This is non-repudiable proof this specific transaction was authorized — required for fully autonomous completion without a human-in-the-loop review step. See [ucp.dev AP2 Mandates](https://ucp.dev/latest/specification/ap2-mandates/) and [UCP and AP2](https://ucp.dev/documentation/ucp-and-ap2/) for the full flow.

## `available_instruments` Resolution

You declare your supported instrument types/constraints in your own profile; the business intersects that with its own support and the cart context, then returns the authoritative `available_instruments` in its response. Always treat that response value as final — never override it with your own profile's declaration.

## PCI Scope Minimization

- Handle only opaque tokens/encrypted payloads/mandates — never raw PANs or CVVs.
- Clear credentials from memory immediately after submission; re-acquire on expiration rather than caching raw credentials.
- Always use HTTPS; validate handler configs before executing their protocol.

## Request Signing (RFC 9421)

When using HTTP Message Signatures, sign with a key referenced by your own profile's `keys`:

```http
POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Digest: sha-256=:X48E9q...:
Signature-Input: sig1=("@method" "@authority" "@path" "idempotency-key" "content-digest" "content-type");keyid="platform-2026"
Signature: sig1=:MEUCIQ...:
```

## Signals & Attribution

- `signals` (e.g. `dev.ucp.buyer_ip`, `dev.ucp.user_agent`) MUST be values you directly observed or independently verified — never buyer-asserted claims. All signal keys are reverse-domain namespaced (well-known ones under `dev.ucp.*`).
- `attribution` carries your own campaign/click-ID context (e.g. `gclid`, `campaign_source`) — optional and informational only; its presence or absence MUST NOT affect negotiation or the response.
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: 471kUpdated 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