Pago en Superposición - Dodo Payments Documentation

Descripción general

El SDK de Pago de Dodo Payments proporciona una forma fluida de integrar nuestra superposición de pago en su aplicación web. Construido con TypeScript y estándares web modernos, ofrece una solución robusta para manejar pagos con manejo de eventos en tiempo real y temas personalizables.

Imagen de portada del Checkout en Superposición

Demostración

Interactive Demo

Vea el overlay checkout en acción con nuestra demostración en vivo.

Inicio Rápido

Comience con el SDK de Pago de Dodo Payments en solo unas pocas líneas de código:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

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

Obtén tu URL de checkout desde la create checkout session API.

Guía de Integración Paso a Paso

Install the SDK

Instale el SDK de Pago de Dodo Payments utilizando su gestor de paquetes preferido:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Inicialice el SDK en su aplicación, típicamente en su 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", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Siempre inicializa el SDK antes de intentar abrir el checkout. La inicialización debe hacerse una vez cuando se carga tu aplicación.

Create a Checkout Button Component

Cree un componente que abra la superposición de pago:

// 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(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://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 Checkout to Your Page

Utilice el componente de botón de pago en su 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 Success and Failure Pages

Cree páginas para manejar redirecciones de 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

Inicie su servidor de desarrollo:

npm run dev

Pruebe el flujo de pago:
- Haga clic en el botón de pago
- Verifique que la superposición aparezca
- Pruebe el flujo de pago utilizando credenciales de prueba
- Confirme que las redirecciones funcionen correctamente

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

Go Live

Cuando esté listo para producción:

Cambia el modo a 'live':

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

Actualice sus URLs de pago para usar sesiones de pago en vivo desde su backend
Pruebe el flujo completo en producción
Monitoree eventos y errores

Referencia de API

Configuración

Opciones de Inicialización

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

Option	Type	Required	Description
`mode`	`"test" \| "live"`	Yes	Environment mode: `'test'` for development, `'live'` for production
`displayType`	`"overlay" \| "inline"`	No	Display type: `'overlay'` for modal checkout (default), `'inline'` for embedded checkout
`onEvent`	`function`	Yes	Callback function for handling checkout events

Opciones de Pago

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

Opción	Tipo	Requerido	Descripción
`checkoutUrl`	`string`	Sí	URL de la sesión de checkout desde el API de creación de sesión de checkout
`options.showTimer`	`boolean`	No	Mostrar u ocultar el temporizador de checkout. Por defecto es `true`. Cuando está desactivado, recibirás el evento `checkout.link_expired` cuando expira la sesión.
`options.showSecurityBadge`	`boolean`	No	Mostrar u ocultar la insignia de seguridad. Por defecto es `true`.

Métodos

Abrir Pago

Abre la superposición de pago con la URL de sesión de pago especificada.

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

También puedes pasar opciones adicionales para personalizar el comportamiento del pago:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});

Cerrar Checkout

Cierra programáticamente la superposición de checkout.

DodoPayments.Checkout.close();

Verificar Estado

Devuelve si la superposición de checkout está actualmente abierta.

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

Eventos

El SDK proporciona eventos en tiempo real que puedes escuchar a través del callback onEvent:

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

Tipo de Evento	Descripción
`checkout.opened`	La superposición de checkout se ha abierto
`checkout.form_ready`	El formulario de checkout está listo para recibir la entrada del usuario. Útil para ocultar estados de carga.
`checkout.payment_page_opened`	La página de pago se ha mostrado
`checkout.customer_details_submitted`	Se han enviado el cliente y los detalles de facturación
`checkout.closed`	La superposición de checkout se ha cerrado
`checkout.redirect`	El checkout realizará un redireccionamiento
`checkout.error`	Ocurrió un error durante el checkout
`checkout.link_expired`	Se dispara cuando la sesión de checkout expira. Solo se recibe cuando `showTimer` está configurado en `false`.

Opciones de Implementación

Instalación del Gestor de Paquetes

Instala a través de npm, yarn o pnpm como se muestra en la Guía de Integración Paso a Paso.

Implementación del CDN

Para una integración rápida sin un paso de construcción, puedes usar nuestro 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>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            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://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Personalización del Tema

Puedes personalizar la apariencia del checkout pasando un objeto themeConfig en el parámetro options al abrir el checkout. La configuración del tema admite modos claros y oscuros, permitiendo personalizar colores, bordes, texto, botones y el radio de los bordes.

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 tu tema al crear la sesión de checkout mediante la API, usando en su lugar el parámetro customization.theme_config — consulta Personalización del tema del checkout — o visualmente en la página de diseño del dashboard. Los temas configurados en la sesión se aplican por igual al checkout overlay, inline y hosted.

Esta sección explica la configuración del lado del cliente del tema obsoleto mediante el 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 del checkout para la configuración a nivel de API, o usa la página de diseño del dashboard para configurar los temas visualmente con una vista previa en tiempo real.

Configuración básica del tema

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

Configuración completa del tema

Todas las propiedades disponibles del tema:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Solo modo claro

Si solo quieres personalizar el tema claro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Solo modo oscuro

Si solo quieres personalizar el tema oscuro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Anulación parcial del tema

Puedes anular solo propiedades específicas. El checkout utilizará los valores predeterminados para las propiedades que no especifiques:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Configuración del tema con otras opciones

Puedes combinar la configuración del tema con otras opciones del checkout:

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

Tipos de TypeScript

Para los usuarios de TypeScript, se exportan todos los tipos de configuración del tema:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Gestión de errores

El SDK proporciona información detallada sobre los errores mediante el sistema de eventos. Implementa siempre una gestión adecuada 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);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

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

Prácticas recomendadas

Inicializa una vez: inicializa el SDK una vez cuando se cargue tu aplicación, no en cada intento de checkout
Gestión de errores: implementa siempre 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
URLs válidas: usa siempre URLs de checkout válidas provenientes 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: desactiva el temporizador (showTimer: false) si quieres gestionar manualmente la expiración de la sesión

Solución de problemas

Checkout not opening

Posibles causas:

El SDK no se inicializó antes de llamar a open()
URL de checkout no válida
Errores de JavaScript en la consola
Problemas de conectividad de red

Soluciones:

Verifica que la inicialización del SDK se produzca antes de abrir el checkout
Comprueba si hay errores en la consola
Asegúrate de que la URL de checkout sea válida y provenga de la API de creación de sesiones de checkout
Verifica la conectividad de red

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
Primero, prueba 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 diferentes tamaños de pantalla
Asegúrate de que no haya conflictos de z-index con el overlay

Habilitar billeteras digitales

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

Apple Pay aún no es compatible con el checkout overlay. La compatibilidad con Apple Pay estará disponible próximamente.

Compatibilidad con navegadores

El Checkout SDK de Dodo Payments es compatible con los siguientes navegadores:

Chrome (última versión)
Firefox (última versión)
Safari (última versión)
Edge (última versión)
IE11+

Checkout overlay frente a inline

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

Función	Checkout overlay	Checkout inline
Profundidad de integración	Modal sobre la página	Totalmente integrado en la página
Control del diseño	Limitado	Control total
Branding	Independiente de la página	Integrado de forma fluida
Esfuerzo de implementación	Menor	Mayor
Ideal para	Integración rápida, páginas existentes	Páginas de checkout personalizadas, flujos de alta conversión

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

Recursos relacionados

Inline Checkout

Inserta el checkout directamente en tu página para ofrecer 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 ponte en contacto con nuestro equipo de soporte para desarrolladores.

​Descripción general

​Demostración

Interactive Demo

​Inicio Rápido

​Guía de Integración Paso a Paso

​Referencia de API

​Configuración

​Opciones de Inicialización

​Opciones de Pago

​Métodos

​Abrir Pago

​Cerrar Checkout

​Verificar Estado

​Eventos

​Opciones de Implementación

​Instalación del Gestor de Paquetes

​Implementación del CDN

​Personalización del Tema

​Configuración básica del tema

​Configuración completa del tema

​Solo modo claro

​Solo modo oscuro

​Anulación parcial del tema

​Configuración del tema con otras opciones

​Tipos de TypeScript

​Gestión de errores

​Prácticas recomendadas

​Solución de problemas

​Habilitar billeteras digitales

​Compatibilidad con navegadores

​Checkout overlay frente a inline

​Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Descripción general

Demostración

Inicio Rápido

Guía de Integración Paso a Paso

Referencia de API

Configuración

Opciones de Inicialización

Opciones de Pago

Métodos

Abrir Pago

Cerrar Checkout

Verificar Estado

Eventos

Opciones de Implementación

Instalación del Gestor de Paquetes

Implementación del CDN

Personalización del Tema

Configuración básica del tema

Configuración completa del tema

Solo modo claro

Solo modo oscuro

Anulación parcial del tema

Configuración del tema con otras opciones

Tipos de TypeScript

Gestión de errores

Prácticas recomendadas

Solución de problemas

Habilitar billeteras digitales

Compatibilidad con navegadores

Checkout overlay frente a inline

Recursos relacionados