Introduction to Hosted Checkout and the Checkout SDK

When integrating payments into your application, there are two core approaches:

Hosted Checkout (Redirect) – fast, minimal effort
Embedded Checkout (iFrame) – flexible, fully integrated into your page

Both are built on the Checkout SDK and fully hosted by COPE. The difference is where the user completes the payment.

📄 Full documentation: [Checkout SDK overview - COPE] | [Embedded hosted checkout - COPE]

The Checkout SDK - the shared foundation

Both approaches use the COPE Checkout SDK, which handles product data, cart management, price calculation, and checkout session creation.

Installation:

npm install @copecart/sdk

import { CopeCart } from "@copecart/sdk"  const cope = new CopeCart({   publishableKey: "cope_pk_live_...", })

The typical flow is always the same:

Fetch product
Create cart and add product
Set buyer identity (email, tax location)
Recalculate prices (reprice)
Create checkout session
Send user to payment – via redirect or iFrame

Hosted Checkout (Redirect) - fastest path to accepting payments

Go live fast, without having to touch the checkout experience at all. With Hosted Checkout, the user is redirected to a COPE-hosted checkout page. Your application creates the session, COPE handles the rest.

Flow:

Your system → Checkout URL → COPE checkout page → Result → Your system (via redirect / webhook)

Typical use cases:

Fast payment go-live
Simple products or services
Payment links (e.g. email, WhatsApp, CRM)
Systems without a custom checkout UI

Integration:

const checkout = await cope.checkout(cart.id, {   success_url: "https://your-site.example/thank-you",   cancel_url: "https://your-site.example/cart",   consents: [{ type: "buyer_tos" }], })  cope.redirectToCheckout(checkout)

After successful payment, COPE redirects to success_url with order_id appended:

https://your-site.example/thank-you?order_id=ord_...

Advantages:

Very low implementation time
No frontend development needed
Reduced PCI complexity
Stable, fully managed payment flow

Embedded Checkout (iFrame) - payment directly in your page

The right choice when you want to present your products in your own branding without ever sending users away from your page. With Embedded Checkout, the user stays on your site – COPE renders the payment form inside an iFrame within your layout.

Flow:
Your application → Checkout SDK → COPE iFrame (embedded in your page)

Requirements:

Create a publishable key for the COPE business
Register every parent page origin that will host the iFrame (e.g. https://shop.example.com)
HTTPS only in production (http://localhost for development only)

Integration:

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" }], })  cope.mountCheckout("#cope-checkout-frame", checkout, {   fallback: "redirect",   onReady: () => showCheckoutFrame(),   onSuccess: () => showOrderConfirmation(),   onCancel: () => closeCheckoutFrame(),   onError: ({ code, retryable }) => reportCheckoutError(code, retryable), })

Important technical notes:

The iFrame is created automatically by the SDK – do not build it manually
embed_origin must exactly match the browser origin of the page
https://shop.example.com and https://www.shop.example.com are treated as different origins
Redirect fallback recommended (fallback: "redirect") in case the iFrame fails to load

Event-based control – Embedded Checkout communicates via events:

onReady – iFrame loaded and ready
onSuccess – payment completed successfully
onCancel – user cancelled
onError – error in payment process (incl. retryable flag)
onResize – iFrame height changed

Advantages:

User never leaves your page
Higher conversion through less friction
Full control over surrounding layout and branding
Wallet support (Apple Pay, Google Pay) depending on setup

Hosted vs. Embedded Checkout – when to use which?

Goal	Solution
Accept payments quickly	Hosted Checkout (Redirect)
No custom UI to build	Hosted Checkout (Redirect)
Minimal technical complexity	Hosted Checkout (Redirect)
Keep user on your own page	Embedded Checkout (iFrame)
Integrate checkout directly in app	Embedded Checkout (iFrame)
High-conversion checkout flow	Embedded Checkout (iFrame)

Important foundations for both approaches

Secure server-side session creation
Webhooks for final payment validation
Idempotency (no duplicate payments)
Error and retry handling
Monitoring & logging
HTTPS required