Skip to content
Universal Commerce Protocol Universal Commerce Protocol Protocol registry / en
The UCP standardUCP vs ACPImplementAgentic commerceFramework
ConceptGEOllms.txtGlossaryAgentic paymentsAP2Visa and MastercardB2B agentic commerceMethodologyUse CasesWhy NowFor WhomManifestoFAQResourcesSourcesEcosystemValidatorReadiness diagnosticAboutContact
FR Run the diagnostic →

Reference note

UCP Embedded Protocol: web and native app handoff

How UCP Embedded Protocol uses JSON-RPC, postMessage, origin validation, handshake, delegation, and checkout recovery.

Published . Part of the UCP implementation guide.

UCP Embedded Protocol displays a merchant interface inside a web or native platform while preserving a structured channel. It uses JSON-RPC 2.0, an explicit handshake, and strict origin validation.

Key takeaways

  • Web hosts use postMessage, then may upgrade to MessageChannel.
  • Native apps inject a messaging bridge into their WebView.
  • A handshake failure requires the embedded session to stop.

When should an embedded transport be used?

A checkout fully controlled through API remains the direct path. Embedded transport is useful when a step must stay in the merchant interface: authentication, consent, regulated data entry, or an interaction the API cannot represent.

continue_url connects both environments. The platform opens it in a controlled window, frame, or WebView. The merchant retains its interface while both parties exchange the structured messages defined by the Embedded Protocol specification. The Checkout lifecycle remains the source of business state, while Identity Linking provides identity when the embedded session needs a user token.

How does the web channel work?

At startup, the host and embedded context communicate through window.postMessage(). The host must validate that each message origin matches the origin of the continue_url used to start the session. Checking only a method name is insufficient.

The host may create a MessageChannel and transfer one port in the ready response. If accepted, every later message must use that channel. Otherwise both windows continue with postMessage and origin validation on every exchange.

How does a native WebView communicate?

The application injects a consumer interface named after the capability. For Checkout, the preferred form is window.EmbeddedCheckoutProtocolConsumer. WebKit may expose the bridge through window.webkit.messageHandlers....

The transmitted message is a JSON string containing a JSON-RPC 2.0 request. The host must parse it before processing. In the opposite direction, the app injects a call to EmbeddedCheckoutProtocol or the corresponding Cart object.

The four-step handshake

  1. The embedded context sends ready with requested delegations and optional auth.
  2. The host confirms the UCP version and accepted delegations.
  3. If the host offers a MessagePort, the context switches channels and sends ready again.
  4. If the response contains error_response, the host tears down the context and may redirect through the approved continue_url.

After a handshake error, the embedded context must not send more messages. This prevents a partially initialized interface from modifying the session.

State, delegation, and authentication

Delegation states which side controls part of the experience. A merchant interface can own one step while the host retains the surrounding Checkout flow. State changes still travel through protocol messages, so the host never infers success from a visual event.

The embedded context can request a fresh credential after handshake, for example when an OAuth token expires. The credential travels in a dedicated JSON-RPC response. It must not enter URLs or logs.

Errors to test

Code Meaning Response
abort_error user canceled close cleanly, allow recovery
security_error origin validation failed stop all communication
invalid_state_error messages arrived out of order tear down session
not_supported_error unsupported operation offer another path
timeout_error internal timeout controlled retry may be safe

Integration checklist

  • derive the allowed origin from the validated continue_url;
  • use unique JSON-RPC request IDs;
  • reject messages sent before ready;
  • switch completely to MessagePort after upgrade;
  • tear down the context after a handshake error;
  • redact credentials from telemetry;
  • synchronize through protocol state, never by scraping the embedded DOM.

Sources

Back to the UCP implementation guide · All notes · Lire en français