Embedded

Overview

The Embedded transport allows platforms to embed business checkout flows within their UI using iframes or webviews. This enables human-in-the-loop interactions while maintaining session continuity with autonomous flows.

Endpoint Discovery

Embedded endpoints are declared in the business profile:

{
  "transports": {
    "embedded": {
      "checkout_url": "https://checkout.business.com/embed",
      "allowed_origins": ["https://platform.com", "https://*.platform.com"],
      "features": ["payment", "address", "fulfillment"]
    }
  }
}

Use Cases

Embedding the Checkout

<!-- Platform HTML -->
<iframe
  id="ucp-checkout"
  src="https://checkout.business.com/embed?session_id=sess_abc123"
  style="width: 100%; height: 600px; border: none;"
  allow="payment"
  sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
></iframe>

PostMessage Communication

Parent and embedded frames communicate via postMessage:

Parent to Iframe

// Initialize checkout
const iframe = document.getElementById('ucp-checkout');
iframe.contentWindow.postMessage({
  type: 'ucp:init',
  payload: {
    session_id: 'sess_abc123',
    theme: 'light',
    locale: 'en-US'
  }
}, 'https://checkout.business.com');

// Prefill address
iframe.contentWindow.postMessage({
  type: 'ucp:prefill',
  payload: {
    shipping_address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    }
  }
}, 'https://checkout.business.com');

Iframe to Parent

// Listen for events from iframe
window.addEventListener('message', (event) => {
  // Verify origin
  if (event.origin !== 'https://checkout.business.com') return;

  const { type, payload } = event.data;

  switch (type) {
    case 'ucp:ready':
      console.log('Checkout iframe ready');
      break;

    case 'ucp:resize':
      iframe.style.height = `${payload.height}px`;
      break;

    case 'ucp:complete':
      console.log('Order completed:', payload.order_id);
      handleOrderComplete(payload);
      break;

    case 'ucp:error':
      console.error('Checkout error:', payload);
      break;

    case 'ucp:cancel':
      console.log('User cancelled checkout');
      break;
  }
});

Event Types

Session Handoff

Sessions can be started via REST/MCP and completed via Embedded:

// 1. Agent creates session via REST
const response = await fetch('https://api.business.com/checkout/sessions', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ...' },
  body: JSON.stringify({
    items: [{ product_id: 'SKU-001', quantity: 1 }]
  })
});

const { session_id, checkout_url } = await response.json();

// 2. Open embedded checkout for human payment
window.open(
  `${checkout_url}?session_id=${session_id}&mode=embedded`,
  'ucp-checkout',
  'width=500,height=700'
);

// 3. Listen for completion
window.addEventListener('message', (event) => {
  if (event.data.type === 'ucp:complete') {
    // Order completed by human
    continueWithAgent(event.data.payload.order_id);
  }
});

Security Considerations

• Origin validation - Always verify message origin
• CSP headers - Configure Content-Security-Policy
• Sandbox attribute - Restrict iframe capabilities
• HTTPS only - Both parent and iframe must use HTTPS

Content Security Policy

<!-- Business checkout page headers -->
Content-Security-Policy: frame-ancestors https://platform.com https://*.platform.com;

<!-- Platform page headers -->
Content-Security-Policy: frame-src https://checkout.business.com;

Mobile Webview

// React Native example
import { WebView } from 'react-native-webview';

<WebView
  source={{ uri: checkoutUrl }}
  onMessage={(event) => {
    const data = JSON.parse(event.nativeEvent.data);
    if (data.type === 'ucp:complete') {
      navigation.navigate('OrderConfirmation', {
        orderId: data.payload.order_id
      });
    }
  }}
  injectedJavaScript={`
    window.ReactNativeWebView = window.ReactNativeWebView || {};
    window.addEventListener('message', (e) => {
      window.ReactNativeWebView.postMessage(JSON.stringify(e.data));
    });
  `}
/>

Theming

// Pass theme configuration
iframe.contentWindow.postMessage({
  type: 'ucp:init',
  payload: {
    theme: {
      mode: 'dark',
      primaryColor: '#E62117',
      fontFamily: 'Inter, sans-serif',
      borderRadius: '0px'
    }
  }
}, 'https://checkout.business.com');

Next Steps

• See Business Integration for setup
• Learn about Checkout Capability for session management
• Explore REST Transport for session creation