Checkout Capability - EP Binding

Checkout Capability - EP Binding

Introduction

Embedded Checkout Protocol (ECP) is a checkout-specific implementation of UCP’s Embedded Protocol (EP) transport binding that enables a host to embed a business’s checkout interface, receive events as the buyer interacts with the checkout, and delegate key user actions such as address and payment selection. ECP is a transport binding (like REST)—it defines how to communicate, not what data exists.

W3C Payment Request Conceptual Alignment

ECP draws inspiration from the W3C Payment Request API, adapting its mental model for embedded checkout scenarios. Developers familiar with Payment Request will recognize similar patterns, though the execution model differs:

W3C Payment Request: Browser-controlled. The business calls show() and the browser renders a native payment sheet. Events flow from the payment handler to the business.

Embedded Checkout: Business-controlled. The host embeds the business’s checkout UI. The business drives the checkout flow and events flow from the checkout to the host, allowing the host to respond to user actions (e.g., selecting an address or payment method).

Key Participants

Participant	Role
Business	Provides the embeddable checkout UI and drives the checkout flow.
Host	Embeds the business checkout and delegates user actions.

Protocol Overview

ECP uses JSON-RPC 2.0 over a postMessage channel (or equivalent transport) between the host and the embedded checkout frame. The embedded checkout dispatches events as the buyer interacts, and the host responds to delegate specific actions back to the checkout.

Message Flow

+--------+                          +--------------+
|  Host  |                          |  Checkout    |
|        |                          |  (embedded)  |
+---+----+                          +------+-------+
    |                                      |
    |  1. Embed checkout iframe            |
    |------------------------------------->|
    |                                      |
    |  2. checkout.ready event             |
    |<-------------------------------------|
    |                                      |
    |  3. User selects address             |
    |      -> checkout.address_change      |
    |<-------------------------------------|
    |                                      |
    |  4. Host responds with address data  |
    |------------------------------------->|
    |                                      |
    |  5. checkout.payment_request event   |
    |<-------------------------------------|
    |                                      |
    |  6. Host provides payment instrument |
    |------------------------------------->|
    |                                      |
    |  7. checkout.complete event          |
    |<-------------------------------------|

Events

The embedded checkout dispatches the following events to the host:

Event	Description
checkout.ready	Checkout has loaded and is ready for interaction.
checkout.change	Checkout state has changed (e.g., line items, totals).
checkout.address_change	Buyer has entered or changed their address.
checkout.payment_request	Buyer is ready to pay; checkout requests a payment instrument.
checkout.complete	Checkout has completed and an order was placed.
checkout.cancel	Buyer canceled the checkout.
checkout.error	An error occurred in the checkout.

Host Methods

The host can call the following methods on the embedded checkout:

Method	Description
checkout.provide_address	Respond to an address_change event with selected address.
checkout.provide_payment	Provide a payment instrument for checkout completion.
checkout.update	Send updated checkout data (e.g., buyer context).

Conformance

A conforming ECP host implementation MUST:

1. Embed the checkout UI in an iframe or equivalent isolated context.
2. Handle all checkout.* events dispatched by the embedded checkout.
3. Respond to checkout.address_change and checkout.payment_request events.
4. Forward payment instruments in the format specified by the business’s payment handlers.
5. Respect the checkout’s complete and cancel events.