Introducción al Hosted Checkout y al Checkout SDK

Al integrar pagos en tu aplicación, existen dos enfoques principales:

Hosted Checkout (Redirect) – rápido, mínimo esfuerzo
Embedded Checkout (iFrame) – flexible, completamente integrado en tu página

Ambas opciones se basan en el Checkout SDK y son alojadas íntegramente por COPE. La diferencia está en dónde el usuario completa el pago.

📄 Documentación completa: [Checkout SDK overview - COPE] | [Embedded hosted checkout - COPE]

El Checkout SDK - la base común

Ambas variantes utilizan el COPE Checkout SDK, que gestiona datos de producto, carrito, cálculo de precios y creación de la sesión de pago.

Instalación:

npm install @copecart/sdk

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

El flujo típico es siempre el mismo:

Obtener producto
Crear carrito y añadir producto
Establecer identidad del comprador (email, ubicación fiscal)
Recalcular precios (reprice)
Crear sesión de checkout
Enviar al usuario al pago – via redirect o iFrame

Hosted Checkout (Redirect) – la forma más rápida de aceptar pagos

Lanza rápido sin tener que tocar la experiencia de pago. Con Hosted Checkout, el usuario es redirigido a una página de pago alojada por COPE. Tu aplicación crea la sesión, COPE se encarga del resto.

Flujo:
Tu sistema → URL de checkout → Página de checkout de COPE → Resultado → Tu sistema (via redirect / webhook)

Casos de uso típicos:

Lanzamiento rápido de pagos
Productos o servicios simples
Enlaces de pago (p. ej. email, WhatsApp, CRM)
Sistemas sin UI de checkout propia

Integración:

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)

Tras el pago exitoso, COPE redirige a success_url con order_id añadido:

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

Ventajas:

Tiempo de implementación muy reducido
Sin desarrollo frontend necesario
Complejidad PCI reducida
Flujo de pago estable y completamente gestionado

Embedded Checkout (iFrame) - pago directamente en tu página

La opción correcta cuando quieres presentar tus productos con tu propio branding sin redirigir al usuario a otra página. Con Embedded Checkout, el usuario permanece en tu sitio – COPE renderiza el formulario de pago en un iFrame dentro de tu layout.

Flujo:
Tu aplicación → Checkout SDK → iFrame de COPE (integrado en tu página)

Requisitos:

Crear una clave publicable para el negocio en COPE
Registrar cada origen de página que vaya a alojar el iFrame (p. ej. https://shop.example.com)
Solo HTTPS en producción (http://localhost solo para desarrollo)

Integración:

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), })

Notas técnicas importantes:

El iFrame es creado automáticamente por el SDK – no construirlo manualmente
embed_origin debe coincidir exactamente con el origen del navegador de la página
https://shop.example.com y https://www.shop.example.com se tratan como orígenes distintos
Se recomienda fallback a redirect (fallback: "redirect") por si el iFrame no carga

Control basado en eventos – Embedded Checkout se comunica mediante eventos:

onReady – iFrame cargado y listo
onSuccess – pago completado con éxito
onCancel – usuario canceló
onError – error en el proceso de pago (incl. flag retryable)
onResize – altura del iFrame ha cambiado

Ventajas:

El usuario nunca abandona tu página
Mayor conversión con menos fricción
Control total sobre el layout y branding circundante
Soporte de wallets (Apple Pay, Google Pay) según configuración

Hosted vs. Embedded Checkout - ¿cuándo usar cuál?

Objetivo	Solución
Aceptar pagos rápidamente	Hosted Checkout (Redirect)
Sin UI propia que construir	Hosted Checkout (Redirect)
Complejidad técnica mínima	Hosted Checkout (Redirect)
Mantener al usuario en tu página	Embedded Checkout (iFrame)
Integrar checkout directamente en la app	Embedded Checkout (iFrame)
Flujo de checkout de alta conversión	Embedded Checkout (iFrame)

Fundamentos importantes para ambas variantes

Creación segura de sesiones en el servidor
Webhooks para validación final del pago
Idempotencia (sin pagos duplicados)
Gestión de errores y reintentos
Monitoreo y logging
HTTPS obligatorio