Embedded hosted checkout

Embedded hosted checkout lets your page keep its layout while COPE renders the payment form inside an iframe. Your site owns the surrounding experience. COPE owns the checkout route, payment collection, tax finality, order creation, and buyer-facing terminal states. Use embedded checkout when you need a custom storefront or in-page checkout modal. Use redirect checkout when the simplest integration is enough or when a browser blocks the iframe flow.

Requirements

Before creating embedded checkout sessions:

Create a Checkout SDK publishable key for the COPE business.
Register every parent page origin that may host the iframe, for example https://shop.example.com.
Use an origin only: scheme, host, and optional port. Do not include a path, query string, fragment, or userinfo.
Use HTTPS in production. http://localhost is only for development and test environments.
Register the success and cancel URLs used for redirect-based completion or fallback. They are matched as complete URL strings, not as origins — see redirect URLs.

The parent origin must exactly match the browser page origin that calls checkout({ embed_origin }). https://shop.example.com and https://www.shop.example.com are different origins. Embed origins and redirect URLs are separate allowlists with different matching rules. An embed origin is scheme, host, and optional port only. A redirect URL is the entire URL, including its path and any query string.

Create an iframe checkout

import { CopeCart } from "@copecart/sdk"

const cope = new CopeCart({
  publishableKey: "cope_pk_live_...",
})

async function openEmbeddedCheckout(productId: string, planId: number) {
  const cart = await cope.createCart({ currency: "EUR" })

  await cope.addLine(cart.id, {
    product_id: productId,
    plan_id: planId,
  })

  await cope.setBuyerIdentity(cart.id, {
    email: "buyer@example.com",
    tax_location: {
      country: "DE",
      postal_code: "10115",
    },
  })

  await cope.reprice(cart.id)

  const checkout = await cope.checkout(cart.id, {
    embed_origin: window.location.origin,
    success_url: "https://shop.example.com/thank-you",
    cancel_url: "https://shop.example.com/cart",
    consents: [{ type: "buyer_tos" }],
  })

  return cope.mountCheckout("#cope-checkout-frame", checkout, {
    fallback: "redirect",
    onReady: () => showCheckoutFrame(),
    onResize: ({ height }) => resizeContainer(height),
    onSuccess: () => showOrderConfirmation(),
    onCancel: () => closeCheckoutFrame(),
    onError: ({ code, retryable }) => reportCheckoutError(code, retryable),
  })
}

The checkout response includes both URL shapes:

Field	Meaning
`checkout.checkoutUrl`	Hosted checkout redirect route, for example `https://app.cope.com/checkout/:token`.
`checkout.embedCheckoutUrl`	Iframe route, for example `https://app.cope.com/checkout/embed/:token`.
`checkout.embedOrigin`	The approved parent origin returned by COPE when `embed_origin` is valid.

mountCheckout() refuses to mount when checkout.embedOrigin is missing or does not exactly match window.location.origin. It also refuses an embedCheckoutUrl — or a checkoutUrl used for fallback: "redirect" — whose origin is not the configured checkoutBaseUrl.

Mounting a phone offer

An offer is created on your server, not in the browser, so there is no cart to build and no CheckoutResult to pass. The offer response carries the fields mountCheckout() actually needs:

// The browser still needs a publishable key, even though the offer itself was
// created server-side with the secret one. `checkoutBaseUrl` must name the origin
// the offer's `embed_url` is on — outside production that is not app.cope.com.
const cope = new CopeCart({
  publishableKey: "cope_pk_...",
  checkoutBaseUrl: "https://app.cope.com",
})

async function openOffer(offer: Offer) {
  // Both embed fields are absent — not null — unless the offer was created with an
  // embed_origin that resolves, so narrow both before mounting.
  if (!offer.embed_url || !offer.embed_origin) {
    window.location.href = offer.public_url // hosted fallback
    return
  }

  cope.mountCheckout("#cope-checkout-frame", {
    embedCheckoutUrl: offer.embed_url,
    embedOrigin: offer.embed_origin,
    checkoutUrl: offer.public_url, // required only by fallback: "redirect"
  }, {
    onSuccess: () => showOrderConfirmation(),
  })
}

Pass offer.public_url as checkoutUrl if you use fallback: "redirect". The SDK will not derive one: an offer’s recovery page is /offers/:uuid, which renders the offer’s state, while the hosted checkout route would refuse in exactly the cases the fallback exists for — and it would carry the offer’s payment-capable access token into the address bar. The iframe, the handshake and the events are identical to a cart checkout. Two sections below do not apply to offers: Test your integration builds a cart, and the embed_origin troubleshooting row points at checkout() — for an offer, send embed_origin on create-offer instead.

Mount behavior

mountCheckout() creates the iframe for you:

src is checkout.embedCheckoutUrl.
title defaults to COPE checkout.
allow is set to payment * for browser wallet support.
referrerPolicy is set to no-referrer.
width is set to 100%.
min-height is set to 720px.
No sandbox attribute is added by the SDK.

Do not build the iframe manually unless you are testing the embed contract. The SDK also performs the trusted mount handshake and filters all iframe messages by origin, source window, message source, and version.

Fallbacks

Set fallback: "redirect" for buyer-safe recovery if the iframe does not complete the trusted ready handshake before readyTimeoutMs.

cope.mountCheckout("#cope-checkout-frame", checkout, {
  fallback: "redirect",
  readyTimeoutMs: 8000,
  onFallbackRedirect: () => {
    console.log("Falling back to hosted checkout")
  },
})

With the default fallback: "error", the SDK calls:

onError({ code: "load_failed", retryable: true })

Events

The iframe sends sanitized events to the SDK. Callback payloads do not include checkout credentials, payment client secrets, or buyer PII.

type CheckoutEmbedEvent =
  | { type: "ready"; messageId?: string; timestamp?: string }
  | {
      type: "resize"
      payload: { height: number }
      messageId?: string
      timestamp?: string
    }
  | {
      type: "error"
      payload: {
        code: "not_found" | "load_failed" | "embed_not_allowed" | "confirm_failed"
        retryable: boolean
      }
      messageId?: string
      timestamp?: string
    }
  | {
      type: "terminal"
      payload: {
        status: "expired" | "completed" | "already_completed" | "cancelled" | "processing"
      }
      messageId?: string
      timestamp?: string
    }

Use onMessage when you need the raw sanitized event stream:

cope.mountCheckout("#cope-checkout-frame", checkout, {
  onMessage: (event) => {
    analytics.track("cope_checkout_embed_event", event)
  },
})

onSuccess and onCancel are convenience callbacks derived from terminal events. Only a live completed fires onSuccess. already_completed means the checkout was paid before this iframe mounted — a refresh after success, or a re-opened offer link — so fulfilment must not run again; processing means an asynchronous rail accepted the payment but the order is not final yet.

Security model

Embedded checkout has two layers of authorization:

COPE validates embed_origin against the business checkout embed domain allowlist when checkout is created.
The iframe route validates the same embed contract before rendering checkout UI.

The SDK sends the mount message with a specific targetOrigin; it never uses *. It accepts iframe messages only when:

event.origin matches the checkout iframe origin.
event.source is the mounted iframe window.
event.data.source is cope.checkout.
event.data.version is 1.

The regular hosted checkout route is frame-denied. Only /checkout/embed/:token is intended for iframe rendering.

Test your integration

Use a development or staging page that matches the origin you registered for the COPE business. Exercise the full flow before launch:

Create a cart.
Add a product and payment plan.
Set buyer identity.
Reprice.
Create checkout with embed_origin.
Mount the iframe and inspect the postMessage conversation.

Also verify rejected unregistered origins, expired checkout sessions, missing mount handshakes, and redirect fallback behavior.

Troubleshooting

Symptom	Likely cause	Fix
`embed_origin_not_allowed` during checkout creation	The page origin is not registered for the COPE business.	Register the exact parent origin and create a new checkout session.
`invalid_redirect_url` during checkout creation	`success_url` or `cancel_url` is not registered. Registering the origin or the path without its query string does not match.	Register the complete URL exactly as sent, or omit the field to use the first registered URL. See redirect URLs.
`mountCheckout requires checkout.embedOrigin`	Checkout was created without `embed_origin`, or the API rejected the embed origin.	Pass `embed_origin: window.location.origin` and check the checkout response.
`Checkout embed origin ... does not match current origin`	Checkout was created for a different parent origin.	Create checkout from the same origin that will mount it.
Iframe never becomes ready	The token is invalid, expired, blocked by headers, or the mount handshake failed.	Use `fallback: "redirect"` and inspect `onError` and browser console output.
Browser wallet is unavailable	Wallet domain registration or cross-origin iframe payment permissions are incomplete.	Confirm the iframe uses `allow="payment *"` and verify wallet domain setup for the parent and checkout origins.

​Embedded hosted checkout

​Requirements

​Create an iframe checkout

​Mounting a phone offer

​Mount behavior

​Fallbacks

​Events

​Security model

​Test your integration

​Troubleshooting