orcaqubits/agentic-commerce-skills-plugins/ucp-payment-authentication

UCP Payment Authentication Extension

Before writing code

Fetch live spec: Web-search site:ucp.dev specification payment extensions authentication and fetch the extension page plus the two action pages (device-data-collection, three-ds-challenge) for the exact action config fields and handshake message names. This extension touches payment security — do not implement it from memory.

Conceptual Architecture

What it does, and what it does not

The extension standardizes the browser-surface interactions a platform may need to process while a payment attempt is underway. It extends the checkout capability with namespace dev.ucp.common.payment.authentication.

It deliberately does not replace EMV 3DS protocol details. UCP carries where the surface lives and when to show it; the 3DS protocol itself remains between the issuer, the network, and the payment handler.

Two actions

Device data collection is invisible by design. Rendering it visibly, or skipping it because "nothing shows", breaks the authentication that follows.

Action occurrence fields

Each emitted action carries:

• id — unique action identifier
• payment_instrument_id — which payment instrument in the checkout this applies to
• url — the surface endpoint, validated against handler-approved origins

Sequencing

The business emits device data collection first (if needed), waits for completion, then emits the 3DS challenge in a subsequent checkout response. These are two round-trips, not one payload. A platform that tries to render both at once has misread the flow.

The ready handshake

Both surfaces follow the same three-step handshake:

1. Surface sends action.ready
2. Platform confirms
3. Surface signals action.done or action.error

The confirmation step exists so the platform can guarantee the surface is mounted and isolated before the authentication flow starts.

Platform responsibilities

• Validate origins against the handler-approved list before loading any surface url.
• Maintain isolation — the surface must not be able to reach into the host page.
• Reconcile outcomes against the authoritative checkout state. An action.done is a signal that the surface finished, not proof that authentication succeeded. The checkout response is authoritative; re-read it.

Implementation Guidance

• Treat url as untrusted until origin-validated, every time — not once at configuration.
• Handle action.error and timeout as distinct paths; a challenge the buyer abandons is not the same as one that failed.
• Never infer payment success from the action handshake. Complete the checkout and read the result.
• Test the human-abandonment path explicitly; it is the most common real-world outcome after "success".
• Reference implementation: https://github.com/Universal-Commerce-Protocol/samples