

Descripción general
El Komerza Embed SDK te permite integrar de forma transparente nuestra experiencia de pago directamente en tu sitio web. En lugar de redirigir a los clientes a una página de pago separada, el embed crea una superposición modal que mantiene a los usuarios en tu sitio mientras proporciona un flujo de pago seguro y optimizado.Demo en vivo
Ve el Embed SDK en acción con nuestra demo interactiva
También integra nuestro script de análisis para recuperar análisis de
visitantes en tu sitio personalizado para obtener información completa sobre
el recorrido del cliente.
Características
Integración transparente
La superposición modal mantiene a los clientes en tu sitio durante el pago
Ligero
Paquete JavaScript mínimo sin dependencias externas
Soporte de temas
Temas claro, oscuro y automático para combinar con el diseño de tu sitio
Compatible con CSP
Soporte completo de política de seguridad de contenido con integración de nonce
Inicio rápido
Agrega el siguiente script al<head> de tu sitio web o antes de la etiqueta de cierre </body>:
Método 1: Atributos de datos (Recomendado para casos simples)
La forma más fácil de agregar botones de pago a tu sitio. Solo agrega atributos de datos a cualquier botón o elemento:Referencia de atributos de datos
Deja que el cliente elija la variante
data-kmrza-variant-id es opcional. Si lo omites, el checkout se abre con un selector de variante para que el cliente elija antes de pagar.
data-kmrza-variant-id cuando quieras que el cliente llegue directamente a una variante concreta.
Método 2: API de JavaScript (Para casos de uso avanzados)
Para mayor control, usa la API de JavaScript para abrir el pago programáticamente:Múltiples artículos
Puedes agregar varios productos al pago a la vez:Guía de implementación completa
Configuración HTML
Aquí hay un ejemplo completo de página HTML:Integración JavaScript
- Integración básica
- Integración avanzada
- Integración React
Referencia de API
Komerza.init(options?)
Inicializa el embed y vincula automáticamente todos los elementos con atributos data-kmrza-*.
Esta sección aún no está traducida y se muestra en inglés por ahora.
nonce(optional): CSP nonce for injected styles and scriptspreload(optional): Boot the checkout frame ahead of the click (default:true). See below.
Preloading the checkout
By default the SDK boots the checkout frame hidden as soon as the first buy button withdata-kmrza-* attributes scrolls into view. The frame loads the checkout shell, its JavaScript and the connection to the Komerza API while the customer is still reading, so when they click the only thing left to wait for is their basket. Without it, the frame is created on the press that precedes the click, which saves far less.
What it costs: one hidden load of the checkout page (the page and its scripts) from checkout.komerza.com per page view with a visible buy button, whether or not anyone clicks. The checkout assets are cached at Cloudflare’s edge, so the load is cheap and does not touch your own server. Preloading is skipped automatically when the customer’s browser has data saver turned on, and it waits until the tab is actually visible, so a tab opened in the background pays nothing until it is brought to the front. The frame is the same iframe the modal uses, so your frame-src CSP rule already covers it.
Turn it off by passing preload: false:
Komerza.init() yourself, set it on the tag instead:
Komerza.open(options)
Abre la modal de pago programáticamente.
Komerza.close()
Cierra la modal de pago programáticamente.
Komerza.preload()
Boots the checkout frame hidden, ahead of a click. This is what the SDK does on its own when a data-kmrza-* button scrolls into view (see Preloading the checkout), but if you open checkout only through Komerza.open() there are no bound buttons to watch, so nothing preloads unless you ask for it. Call it once your own buy button is on screen:
Komerza.open() reuses the booted frame if it is still fresh and then only waits for the basket; a frame left idle for several minutes is discarded and checkout opens the usual way.
Integración Next.js
Solución de problemas
El pago no se abre
- Asegúrate de que el script está cargado (se recomienda el atributo
defer) - Revisa la consola del navegador para ver errores
- Verifica que tus IDs de producto y variante sean correctos
- Si usas atributos de datos, asegúrate de que
Komerza.init()se llama después de que el DOM esté cargado
El modal aparece detrás de otros elementos
El modal usa un z-index alto (9999). Si sigue detrás de otros elementos, revisa tu CSS para valores z-index competidores.I see a request to checkout.komerza.com/embed on page load
That is the SDK preloading the checkout frame because a buy button is on screen - see Preloading the checkout. It is one hidden load of the checkout page per page view (the page and its scripts, served from Cloudflare’s cache), and no order or checkout session is created until the customer clicks. If you would rather it did not happen, passpreload: false to Komerza.init() or add data-kmrza-preload="false" to the script tag.
Afiliados
El Komerza Embed SDK admite el seguimiento de afiliados de forma nativa. El parámetro de consulta?ref se admite automáticamente y la cookie kmrza_affiliate se lee automáticamente.
Política de seguridad de contenido (CSP)
Mejores prácticas
Rendimiento
Rendimiento
- Carga el script del SDK de forma asíncrona cuando sea posible
- Inicializa el SDK temprano pero abre los modales solo con la interacción del usuario
- Implementa estados de carga adecuados para los botones de compra
Experiencia de usuario
Experiencia de usuario
- Proporciona indicadores de carga claros - Maneja los errores de red graciosamente con URLs de respaldo - Admite la navegación por teclado (Esc para cerrar)
Seguridad
Seguridad
- Usa siempre encabezados CSP en producción
- Valida los IDs de producto y variante antes de abrir el pago
- Nunca expongas datos sensibles en el código del lado del cliente
Soporte
¿Necesitas ayuda con la integración?Página de demo
Demo interactiva con ejemplos de código fuente
Soporte para desarrolladores
Obtén soporte técnico para problemas de integración