Pago en Superposición

Overlay checkout abre una ventana modal sobre tu página. Los clientes introducen sus datos de pago en el modal mientras tu página permanece visible detrás. Cuando cierran el modal, el control vuelve a tu página. Cuando completan el pago, se les redirige a return_url.

Modal de overlay checkout mostrado sobre una página de producto

Interactive Demo

Mira overlay checkout en acción con nuestra demostración en vivo.

Inicio rápido

Instala el SDK, inicialízalo y abre el checkout con una URL de checkout de la API de creación de sesiones de checkout:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

Integración paso a paso

Install the SDK

Instala mediante npm, yarn o pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Llama a Initialize una vez cuando se cargue tu aplicación, normalmente en tu componente principal o punto de entrada de la aplicación:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Inicializa siempre el SDK antes de abrir el checkout. Inicialízalo una vez cuando se cargue tu aplicación, no antes de cada intento de checkout.

Create a Checkout Button

Crea un componente que abra el modal de checkout:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add the Button to Your Page

Usa el componente de botón de checkout en tu aplicación:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Redirects

Crea páginas para gestionar las redirecciones del checkout después del pago:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

Inicia tu servidor de desarrollo:

npm run dev

Prueba el flujo de checkout:
- Haz clic en el botón de checkout
- Verifica que aparezca el modal
- Prueba el flujo de pago con credenciales de prueba
- Confirma que las redirecciones funcionen correctamente

Deberías ver los eventos de checkout registrados en la consola de tu navegador.

Go Live

Cuando estés listo para producción:

Cambia el modo a 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Actualiza las URL de checkout para usar sesiones de checkout activas desde tu backend
Prueba el flujo completo en producción
Supervisa los eventos y errores

Referencia de la API

Inicializar

Llama a Initialize una vez para configurar el SDK:

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

Opción	Tipo	Obligatorio	Descripción
`mode`	`"test" \| "live"`	Sí	Modo de entorno: `"test"` para desarrollo, `"live"` para producción
`displayType`	`"overlay" \| "inline"`	No	Tipo de visualización: `"overlay"` para modal checkout (predeterminado), `"inline"` para embedded checkout
`onEvent`	`function`	Sí	Función de callback para gestionar eventos de checkout

Abrir checkout

Abre el modal de checkout:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Opción	Tipo	Obligatorio	Descripción
`checkoutUrl`	`string`	Sí	URL de la sesión de checkout de la API de creación de sesiones de checkout
`options.showTimer`	`boolean`	No	Muestra u oculta el temporizador de la sesión. El valor predeterminado es `true`. Cuando está deshabilitado, recibes el evento `checkout.link_expired` cuando la sesión caduca.
`options.showSecurityBadge`	`boolean`	No	Muestra u oculta la insignia de seguridad. El valor predeterminado es `true`
`options.manualRedirect`	`boolean`	No	Cuando es `true`, evita las redirecciones automáticas. Checkout emite `checkout.status` con el resultado del pago y `checkout.redirect_requested` con la URL que se debe abrir, y tú gestionas la navegación
`options.themeConfig`	`ThemeConfig`	No	Obsoleto. Configura el tema en el servidor al crear la sesión de checkout
`options.payButtonText`	`string`	No	Texto personalizado para el botón de pago
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	No	Tamaño de fuente global para el checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	No	Peso de fuente global para el checkout

Cerrar checkout

Cierra el modal mediante programación:

DodoPayments.Checkout.close();

Comprobar estado

Comprueba si el modal está abierto actualmente:

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Eventos

Escucha los eventos de checkout mediante el callback onEvent proporcionado a Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Evento	Descripción
`checkout.opened`	El modal se ha abierto
`checkout.form_ready`	El formulario está listo para que el usuario introduzca datos. Úsalo para ocultar los estados de carga
`checkout.payment_page_opened`	Se muestra la página de pago
`checkout.customer_details_submitted`	Se han enviado los datos del cliente y de facturación
`checkout.closed`	El modal se ha cerrado
`checkout.redirect`	Checkout realizará una redirección (por ejemplo, a una página bancaria)
`checkout.error`	Se produjo un error durante el checkout
`checkout.link_expired`	La sesión de checkout caducó. Solo se recibe cuando `showTimer` está establecido en `false`.

Implementación mediante CDN

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

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dodo Payments Checkout</title>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        console.log('Checkout event:', event);
      }
    });
  </script>
</head>
<body>
  <button onclick="openCheckout()">Checkout Now</button>

  <script>
    function openCheckout() {
      DodoPaymentsCheckout.DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Personalización del tema

La opción themeConfig del lado del cliente está obsoleta y se eliminará en la próxima versión principal del Checkout SDK (v2.0.0). Al pasarla, se registra una advertencia de obsolescencia en la consola del navegador. Configura el tema al crear la sesión de checkout mediante la API usando el parámetro customization.theme_config; consulta Personalización del tema de Checkout, o hazlo visualmente en la página Design del dashboard. Los temas configurados en la sesión se aplican por igual a overlay, inline y hosted checkout.

Esta sección explica la configuración del lado del cliente del tema obsoleto mediante Checkout SDK. El enfoque recomendado es configurar los temas del lado del servidor al crear una sesión de checkout mediante la API usando el parámetro theme_config. Consulta Personalización del tema de Checkout para la configuración a nivel de API, o usa la página Design del dashboard para configurar los temas visualmente con una vista previa en vivo.

Si debes usar la configuración del tema del lado del cliente, pasa themeConfig en el parámetro options:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Propiedades del tema

Todas las propiedades disponibles del tema para los modos claro y oscuro:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Gestión de errores

Implementa siempre la gestión de errores en tu callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Gestiona siempre el evento checkout.error para ofrecer una buena experiencia de usuario cuando se produzcan errores.

Prácticas recomendadas

Inicializa una vez: Llama a Initialize una vez cuando se cargue tu aplicación, no antes de cada checkout
Gestión de errores: Implementa una gestión adecuada de errores en tu callback de eventos
Modo de prueba: Usa el modo "test" durante el desarrollo y cambia a "live" solo cuando estés listo para producción
Gestión de eventos: Gestiona todos los eventos relevantes para ofrecer una experiencia de usuario completa
URL válidas: Usa siempre URL de checkout válidas de la API de creación de sesiones de checkout
TypeScript: Usa TypeScript para mejorar la seguridad de tipos y la experiencia del desarrollador
Estados de carga: Muestra estados de carga mientras se abre el checkout para mejorar la UX
Gestión del temporizador: Deshabilita el temporizador (showTimer: false) si quieres gestionar manualmente la caducidad de la sesión

Solución de problemas

Events not firing

Posibles causas:

El controlador de eventos no está configurado correctamente
Errores de JavaScript que impiden la propagación de eventos
El SDK no se inicializó correctamente

Soluciones:

Confirma que el controlador de eventos esté configurado correctamente en Initialize()
Comprueba si hay errores de JavaScript en la consola del navegador
Verifica que la inicialización del SDK se haya completado correctamente
Prueba primero con un controlador de eventos sencillo

Styling issues

Posibles causas:

Conflictos de CSS con los estilos de tu aplicación
La configuración del tema no se aplicó correctamente
Problemas de diseño responsive

Soluciones:

Comprueba si hay conflictos de CSS en las DevTools del navegador
Verifica que la configuración del tema sea correcta
Prueba con distintos tamaños de pantalla
Asegúrate de que no haya conflictos de z-index con el modal

Billeteras digitales

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

Apple Pay aún no es compatible con overlay checkout.

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+

Overlay checkout frente a Inline checkout

Elige el tipo de checkout adecuado para tu caso de uso:

Función	Overlay	Inline
Profundidad de integración	Modal sobre la página	Completamente integrado en la página
Control del diseño	Limitado	Control total
Marca	Independiente de la página	Coincide con tu página
Esfuerzo de implementación	Menor	Mayor
Ideal para	Integración rápida, páginas existentes	Páginas de checkout personalizadas, flujos con alta conversión

Usa overlay checkout para una integración más rápida con cambios mínimos en tus páginas existentes. Usa inline checkout cuando quieras el máximo control sobre la experiencia de checkout y una identidad de marca coherente.

Recursos relacionados

Inline Checkout

Inserta el checkout directamente en tu página para obtener experiencias totalmente integradas.

Checkout Sessions API

Crea sesiones de checkout para impulsar tus experiencias de checkout.

Webhooks

Gestiona los eventos de pago del lado del servidor mediante webhooks.

Integration Guide

Guía completa para integrar Dodo Payments.

Para obtener más ayuda, visita nuestra comunidad de Discord o contacta con nuestro equipo de soporte para desarrolladores.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Inicio rápido

Integración paso a paso

Referencia de la API

Inicializar

Abrir checkout

Cerrar checkout

Comprobar estado

Eventos

Implementación mediante CDN

Personalización del tema

Propiedades del tema

Gestión de errores

Prácticas recomendadas

Solución de problemas

Billeteras digitales

Compatibilidad con navegadores

Overlay checkout frente a Inline checkout

Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Inicio rápido

​Integración paso a paso

​Referencia de la API

​Inicializar

​Abrir checkout

​Cerrar checkout

​Comprobar estado

​Eventos

​Implementación mediante CDN

​Personalización del tema

​Propiedades del tema

​Gestión de errores

​Prácticas recomendadas

​Solución de problemas

​Billeteras digitales

​Compatibilidad con navegadores

​Overlay checkout frente a Inline checkout

​Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Inicio rápido

Integración paso a paso

Referencia de la API

Inicializar

Abrir checkout

Cerrar checkout

Comprobar estado

Eventos

Implementación mediante CDN

Personalización del tema

Propiedades del tema

Gestión de errores

Prácticas recomendadas

Solución de problemas

Billeteras digitales

Compatibilidad con navegadores

Overlay checkout frente a Inline checkout

Recursos relacionados