Skip to main content
El checkout integrado inserta un formulario de pago seguro directamente en el diseño de tu página. A diferencia del checkout superpuesto, que se abre como un modal, el checkout integrado pasa a formar parte de tu página. Tú controlas el diseño y puedes mostrar tu propio resumen del pedido junto al formulario de checkout.
Formulario de checkout integrado en una página de producto con resumen del pedido

Cómo funciona

El checkout integrado muestra un frame seguro de Dodo Payments en un contenedor de tu página. El frame gestiona la recopilación de la información del cliente y los datos de pago. Tu página muestra los artículos, los totales y otra información. El SDK permite que tu página y el frame de checkout se comuniquen entre sí. Cuando se completa el checkout, Dodo Payments crea el pago o la suscripción para un producto de suscripción, y envía un webhook para que puedas aprovisionar el acceso.
El frame de checkout integrado gestiona de forma segura toda la información de pago confidencial, lo que garantiza el cumplimiento de PCI sin necesidad de certificaciones adicionales por tu parte.

Qué caracteriza a un buen checkout integrado

Los clientes necesitan saber a quién le compran, qué compran y cuánto pagan. Tu implementación debe incluir:
Ejemplo de checkout integrado con los elementos obligatorios etiquetados

Example inline checkout layout showing required elements

  1. Información recurrente: Si el pago es recurrente, muestra con qué frecuencia se repite y el total que se pagará en la renovación. Si se trata de una prueba, muestra su duración.
  2. Descripciones de los artículos: Una descripción de lo que se está comprando.
  3. Totales de la transacción: Subtotal, impuesto total y total general, incluida la moneda.
  4. Pie de página de Dodo Payments: El frame completo de checkout integrado, incluido el pie de página con información de Dodo Payments, las condiciones de venta y la política de privacidad.
  5. Política de reembolso: Un enlace a tu política de reembolso, si difiere de la política de reembolso estándar de Dodo Payments.
Muestra siempre el frame completo de checkout integrado, incluido el pie de página. Eliminar u ocultar información legal infringe los requisitos de cumplimiento.

Recorrido del cliente

El flujo de checkout depende de la configuración de tu sesión de checkout. Según cómo configures la sesión, los clientes pueden ver toda la información en una sola página o en varios pasos.
1

Customer opens checkout

Abres el checkout integrado pasando una URL de checkout. Usa eventos del SDK, como checkout.breakdown, para mostrar y actualizar información en la página.Página inicial de checkout con lista de artículos y formulario de pago
2

Customer enters their details

En primer lugar, el checkout integrado pide a los clientes que introduzcan su dirección de correo electrónico, seleccionen su país y, cuando sea necesario, introduzcan su código ZIP o código postal. Este paso recopila toda la información necesaria para determinar los impuestos y las opciones de pago disponibles.Puedes rellenar previamente los datos del cliente y mostrar direcciones guardadas para agilizar la experiencia.
3

Customer selects payment method

Después de introducir sus datos, los clientes ven los métodos de pago disponibles y el formulario de pago. Las opciones pueden incluir tarjetas de crédito o débito, PayPal, Apple Pay, Google Pay y otros métodos de pago locales según su ubicación.Muestra los métodos de pago guardados, si están disponibles, para agilizar el checkout.Métodos de pago disponibles y formulario de datos de tarjeta
4

Checkout completed

Dodo Payments dirige cada pago al mejor adquirente para esa venta, con el fin de maximizar las probabilidades de éxito. Los clientes acceden a un flujo de éxito que puedes crear.Pantalla de éxito con marca de confirmación
5

Dodo Payments creates the payment or subscription

Dodo Payments crea el pago o la suscripción para un producto de suscripción, y envía un webhook para que puedas aprovisionar el acceso. El método de pago utilizado por el cliente se guarda para renovaciones o cambios de suscripción.Suscripción creada con notificación de webhook

Inicio rápido

Instala el SDK, inicialízalo para el modo integrado y abre el checkout en un elemento contenedor:
Asegúrate de tener en tu página un elemento contenedor con el id correspondiente: <div id="dodo-inline-checkout"></div>.

Integración paso a paso

1

Install the SDK

Instala mediante npm, yarn o pnpm:
2

Initialize the SDK for Inline Display

Inicializa el SDK y especifica displayType: 'inline'. Escucha el evento checkout.breakdown para actualizar tu interfaz con cálculos de impuestos y totales en tiempo real:
3

Create a Container Element

Añade un elemento a tu HTML donde se inyectará el frame de checkout:
4

Open the Checkout

Llama a DodoPayments.Checkout.open() con checkoutUrl y elementId de tu contenedor:
5

Test Your Integration

  1. Inicia tu servidor de desarrollo:
  1. Prueba el flujo de checkout:
    • Introduce tu correo electrónico y los datos de dirección en el frame integrado
    • Comprueba que tu resumen personalizado del pedido se actualice en tiempo real
    • Prueba el flujo de pago con credenciales de prueba
    • Confirma que las redirecciones funcionen correctamente
Deberías ver eventos checkout.breakdown registrados en la consola del navegador si añadiste un registro de consola en el callback onEvent.
6

Go Live

Cuando estés listo para producción:
  1. Cambia el modo a 'live':
  1. Actualiza las URL de checkout para utilizar sesiones de checkout activas desde tu backend
  2. Prueba el flujo completo en producción

Ejemplo completo de React

Este ejemplo muestra cómo implementar un resumen personalizado del pedido junto al checkout integrado y mantenerlos sincronizados mediante el evento checkout.breakdown:

Referencia de la API

Inicializar

Llama a Initialize una vez para configurar el SDK:

Abrir el checkout

Abre el frame de checkout en un contenedor:

Cerrar el checkout

Elimina el frame de checkout mediante programación y limpia los listeners de eventos:

Comprobar el estado

Comprueba si el frame de checkout está insertado actualmente:

Eventos

El SDK proporciona eventos en tiempo real mediante el callback onEvent. Para el checkout integrado, checkout.breakdown resulta especialmente útil para sincronizar tu interfaz:

Datos del desglose del checkout

El evento checkout.breakdown proporciona información sobre precios e impuestos:
El evento se activa cuando se carga el frame de checkout y cada vez que se recalcula el precio; por ejemplo, cuando el cliente selecciona un país o introduce un código postal que modifica el impuesto. Detalles de los campos: Consejos de integración:
  1. Formato de moneda: Los precios son números enteros expresados en la unidad monetaria más pequeña; por ejemplo, centavos para USD. Para monedas con dos decimales, divide entre 100 antes de aplicar formato con Intl.NumberFormat. Las monedas sin decimales, como JPY, no tienen una unidad menor, por lo que no debes dividirlas.
  2. Gestión de estados iniciales: Cuando el checkout se carga por primera vez, tax y discount pueden ser 0 o null hasta que el usuario proporcione sus datos de facturación o aplique un código. Gestiona estos estados correctamente, por ejemplo, mostrando un guion — u ocultando la fila.
  3. «Total final» frente a «Total»: Aunque total proporciona el cálculo de precio estándar, finalTotal es la fuente de verdad de la transacción. Si finalTotal está presente, refleja exactamente lo que se cobrará en la tarjeta del cliente.
  4. Información en tiempo real: Usa el campo tax para mostrar a los usuarios que los impuestos se están calculando en tiempo real. Esto aporta una sensación dinámica a tu página de checkout y reduce la fricción durante la introducción de la dirección.

Implementación mediante CDN

Para una integración rápida sin un paso de compilación, carga el SDK desde CDN:

Actualizar el método de pago

El checkout integrado admite actualizaciones del método de pago para suscripciones. Cuando un cliente necesita actualizar su método de pago para una suscripción activa o reactivar una suscripción en espera, puedes mostrar el flujo de actualización directamente en el diseño de tu página.

Cómo funciona

  1. Llama a la API de actualización del método de pago para obtener un payment_link:
  1. Pasa el payment_link devuelto como checkoutUrl para abrir el checkout integrado:
El frame integrado muestra únicamente el formulario de recopilación del método de pago. Los clientes pueden introducir los datos de una tarjeta nueva o seleccionar un método de pago guardado sin salir de tu página.

Para suscripciones en espera

Al actualizar el método de pago de una suscripción con estado on_hold, Dodo Payments crea automáticamente un cargo por cualquier deuda pendiente. Supervisa los webhooks payment.succeeded y subscription.active para confirmar la reactivación.
También puedes usar un método de pago guardado existente en lugar de recopilar datos nuevos pasando type: 'existing' con un payment_method_id a la API de actualización del método de pago.

Gestión de errores

Implementa siempre la gestión de errores en tu callback onEvent:
Gestiona siempre el evento checkout.error para ofrecer una buena experiencia de usuario cuando se produzcan errores.

Prácticas recomendadas

  1. Diseño adaptable: Asegúrate de que el elemento contenedor tenga suficiente anchura y altura. Normalmente, el iframe se expandirá para ocupar todo el contenedor.
  2. Sincronización: Usa el evento checkout.breakdown para mantener sincronizados tu resumen personalizado del pedido o tus tablas de precios con lo que ve el usuario en el frame de checkout.
  3. Estados esqueleto: Muestra un indicador de carga en tu contenedor hasta que se active el evento checkout.opened.
  4. Limpieza: Llama a DodoPayments.Checkout.close() cuando se desmonte el componente para limpiar el iframe y los listeners de eventos.
Para implementaciones con modo oscuro, usa #0d0d0d como color de fondo para lograr una integración visual óptima con el frame de checkout integrado.

Validación del estado del pago

No dependas únicamente de los eventos del checkout integrado para determinar si un pago se realizó correctamente o falló. Implementa siempre la validación del lado del servidor mediante webhooks o polling.

Por qué es esencial validar en el servidor

Aunque los eventos del checkout integrado proporcionan información en tiempo real, no deben ser tu única fuente de verdad para el estado del pago. Los problemas de red, los bloqueos del navegador o que los usuarios cierren la página pueden hacer que se pierdan eventos. Para garantizar una validación fiable de los pagos:
  1. Escucha los eventos de webhook: Dodo Payments envía webhooks cuando cambia el estado de un pago
  2. Implementa un mecanismo de polling: Tu frontend debe consultar periódicamente tu servidor para obtener actualizaciones de estado
  3. Combina ambos enfoques: Usa los webhooks como fuente principal y el polling como alternativa

Arquitectura recomendada

Pasos de implementación

1. Escucha los eventos de checkout: Cuando el usuario haga clic en pagar, empieza a preparar la verificación del estado:
2. Consulta tu servidor: Crea un endpoint que compruebe en tu base de datos el estado del pago, actualizado por los webhooks:
3. Gestiona los webhooks en el servidor: Actualiza tu base de datos cuando Dodo envíe webhooks payment.succeeded o payment.failed. Consulta nuestra documentación de Webhooks para obtener más información.

Solución de problemas

  • Comprueba que elementId coincida con el id de un div que exista realmente en el DOM
  • Asegúrate de que displayType: 'inline' se haya pasado a Initialize
  • Comprueba que checkoutUrl sea válido
  • Asegúrate de estar escuchando el evento checkout.breakdown
  • Los impuestos solo se calculan después de que el usuario introduzca un país y un código postal válidos en el frame de checkout

Carteras digitales

Para obtener información detallada sobre la configuración de Apple Pay, Google Pay y otras carteras digitales, consulta la página Carteras digitales.

Configuración rápida de Apple Pay

La verificación del dominio solo es necesaria para el checkout integrado. No es necesaria para el checkout alojado.
Apple Pay no está disponible para el checkout superpuesto.
Apple Pay se verifica por dominio desde el dashboard.
1

Open Wallet domains

Ve a Settings → Payment Methods y, en la fila Apple Pay, haz clic en Manage domains.
Botón Manage domains en la fila Apple Pay de la configuración de Payment Methods

Open Wallet domains from the Apple Pay row

2

Download the domain association file

En el panel de dominios de Wallet, descarga el archivo de asociación.
Panel de dominios de Wallet con el botón Download file

Download the Apple Pay domain association file

3

Register your domain

Haz clic en Register domain e introduce el dominio donde insertas el checkout integrado, por ejemplo shop.example.com; después, haz clic en Continue.
Formulario de registro de dominio con un dominio introducido

Register the domain where you embed inline checkout

4

Host the file on your domain

Aloja el archivo en:
Debe servirse mediante HTTPS, ser accesible sin redirecciones y servirse con Content-Type: application/octet-stream o text/plain.
5

Verify the domain

Haz clic en Verify domain. Dodo Payments confirma que el archivo está disponible y envía tu dominio a Apple.
Pantalla de verificación del dominio con la ruta del archivo de asociación y el botón Verify domain

Verify the hosted association file

6

Confirm it's active

Cuando el estado muestre Active, Apple Pay estará habilitado para ese dominio. Usa el interruptor Enabled para activarlo o desactivarlo por dominio.
Lista de dominios de Wallet que muestra dominios con estado Active de Apple Pay e interruptores Enabled

Verified domains show an Active status

7

Test the integration

  1. Abre el checkout en un dispositivo Apple
  2. Comprueba que aparece el botón de Apple Pay
  3. Completa una transacción de prueba

Compatibilidad con navegadores

El Checkout SDK de Dodo Payments es compatible con:
  • Chrome (última versión)
  • Firefox (última versión)
  • Safari (última versión)
  • Edge (última versión)
  • IE11+

Checkout integrado frente a checkout superpuesto

Elige el tipo de checkout adecuado para tu caso de uso:
Usa el checkout integrado cuando quieras el máximo control sobre la experiencia de checkout y una identidad de marca coherente. Usa el checkout superpuesto para una integración más rápida con cambios mínimos en tus páginas existentes.

Recursos relacionados

Overlay Checkout

Usa el checkout superpuesto para una integración rápida basada en modales.

Checkout Sessions API

Crea sesiones de checkout para impulsar tus experiencias de checkout.

Webhooks

Gestiona los eventos de pago en el servidor mediante webhooks.

Integration Guide

Guía completa para integrar Dodo Payments.
Para obtener más ayuda, visita nuestra comunidad de Discord o ponte en contacto con nuestro equipo de soporte para desarrolladores.
Última modificación el 26 de septiembre de 2026