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.

Esta sección cubre la configuración del tema del lado del cliente usando el SDK de Checkout. También puedes configurar temas del lado del servidor al crear una sesión de checkout a través de la API usando el parámetro theme_config. Consulta Personalización de Temas de Checkout para configuración a nivel de API, o usa la página de Diseño en el panel para configurar temas visualmente con una vista previa en vivo.

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 de tema disponibles:

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 deseas 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 deseas 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",
    },
  },
});

Sobrescritura Parcial del Tema

Puedes sobrescribir solo propiedades específicas. El checkout usará 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 de 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",
};

Manejo de Errores

El SDK proporciona información detallada de errores a través del sistema de eventos. Siempre implementa un manejo adecuado 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");
    }
  }
});

Siempre maneja el evento checkout.error para proporcionar una buena experiencia de usuario cuando ocurren errores.

Mejores Prácticas

Inicializa una vez: Inicializa el SDK una vez cuando tu aplicación se carga, no en cada intento de checkout.
Manejo de errores: Siempre implementa un manejo adecuado 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.
Manejo de eventos: Maneja todos los eventos relevantes para una experiencia de usuario completa.
URLs válidas: Siempre usa URLs de checkout válidas desde el API de creación de sesión de checkout.
TypeScript: Usa TypeScript para una mejor seguridad de tipos y experiencia del desarrollador.
Estados de carga: Muestra estados de carga mientras el checkout se abre para mejorar la UX.
Gestión de temporizador: Desactiva el temporizador (showTimer: false) si deseas manejar la expiración de sesión manualmente.

Solución de Problemas

Checkout not opening

Posibles causas:

SDK no inicializado antes de llamar a open()
URL de checkout inválida
Errores de JavaScript en la consola
Problemas de conectividad de red

Soluciones:

Verifica que la inicialización del SDK ocurra antes de abrir el checkout
Revisa errores en la consola
Asegúrate de que la URL de checkout sea válida y provenga del API de creación de sesión de checkout
Verifica la conectividad de red

Events not firing

Posibles causas:

Manejador de eventos no configurado correctamente
Errores de JavaScript que evitan la propagación de eventos
SDK no inicializado correctamente

Soluciones:

Confirma que el manejador de eventos esté correctamente configurado en Initialize()
Revisa la consola del navegador por errores de JavaScript
Verifica que la inicialización del SDK se haya completado exitosamente
Prueba con un manejador de eventos simple primero

Styling issues

Posibles causas:

Conflictos de CSS con los estilos de tu aplicación
Configuración del tema no aplicada correctamente
Problemas de diseño responsivo

Soluciones:

Verifica conflictos de CSS en las DevTools del navegador
Verifica que la configuración del tema sea correcta
Prueba en diferentes tamaños de pantalla
Asegúrate de que no haya conflictos de z-index con la superposición

Activación de Carteras Digitales

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

Apple Pay aún no es compatible en el checkout en superposición. El soporte para Apple Pay estará disponible pronto.

Soporte de Navegadores

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

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

Checkout en Superposición vs Checkout Inline

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

Característica	Checkout en Superposición	Checkout Inline
Profundidad de integración	Modal sobre la página	Completamente incrustado en la página
Control de diseño	Limitado	Control completo
Branding	Separado de la página	Integración perfecta
Esfuerzo de implementación	Menor	Mayor
Mejor para	Integración rápida, páginas existentes	Páginas de checkout personalizadas, flujos de alta conversión

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

Recursos Relacionados

Inline Checkout

Incrusta el checkout directamente en tu página para experiencias completamente integradas.

Checkout Sessions API

Crea sesiones de checkout para potenciar tus experiencias de checkout.

Webhooks

Maneja eventos de pago del lado del servidor con webhooks.

Integration Guide

Guía completa para integrar Dodo Payments.

Para obtener más ayuda, visita nuestra comunidad de Discord o contacta a 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

​Sobrescritura Parcial del Tema

​Configuración del Tema con Otras Opciones

​Tipos de TypeScript

​Manejo de Errores

​Mejores Prácticas

​Solución de Problemas

​Activación de Carteras Digitales

​Soporte de Navegadores

​Checkout en Superposición vs Checkout 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

Sobrescritura Parcial del Tema

Configuración del Tema con Otras Opciones

Tipos de TypeScript

Manejo de Errores

Mejores Prácticas

Solución de Problemas

Activación de Carteras Digitales

Soporte de Navegadores

Checkout en Superposición vs Checkout Inline

Recursos Relacionados