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 de Pago en Superposición

Demostración

Demostración Interactiva

Vea el pago en superposición 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"
});

Obtenga su URL de pago desde la API de crear sesión de pago.

Guía de Integración Paso a Paso

Instalar el SDK

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

npm install dodopayments-checkout

Inicializar el 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 inicialice el SDK antes de intentar abrir el pago. La inicialización debe ocurrir una vez cuando su aplicación se carga.

Crear un Componente de Botón de Pago

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>
  );
}

Agregar Pago a Su Página

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>
  );
}

Manejar Páginas de Éxito y Fallo

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>
  );
}

Probar Su Integración

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ía ver eventos de pago registrados en la consola de su navegador.

Ir a Producción

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;
}

Opción	Tipo	Requerido	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 pago modal (predeterminado), `'inline'` para pago embebido
`onEvent`	`function`	Sí	Función de callback para manejar eventos de pago

Opciones de Pago

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

Opción	Tipo	Requerido	Descripción
`checkoutUrl`	`string`	Sí	URL de sesión de pago de la API de crear sesión de pago
`options.showTimer`	`boolean`	No	Mostrar u ocultar el temporizador de pago. Por defecto es `true`. Cuando está deshabilitado, recibirás el evento `checkout.link_expired` cuando la sesión expire.
`options.showSecurityBadge`	`boolean`	No	Mostrar u ocultar la insignia de seguridad. Por defecto es `true`.
`options.manualRedirect`	`boolean`	No	Cuando está habilitado, el pago no redirigirá automáticamente después de completarse. En su lugar, recibirás los eventos `checkout.status` y `checkout.redirect_requested` para manejar la redirección tú mismo.

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,
    manualRedirect: true,
  },
});

Al usar manualRedirect, maneja la finalización del pago en tu función de callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Cerrar Pago

Cierra programáticamente la superposición de pago.

DodoPayments.Checkout.close();

Verificar Estado

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

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

Eventos

El SDK proporciona eventos en tiempo real a los que puedes escuchar a través de la función de callback onEvent:

Datos del Evento de Estado de Pago

Cuando manualRedirect está habilitado, recibes el evento checkout.status con los siguientes datos:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Datos del Evento de Redirección de Pago Solicitada

Cuando manualRedirect está habilitado, recibes el evento checkout.redirect_requested con los siguientes datos:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        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;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Tipo de Evento	Descripción
`checkout.opened`	La superposición de pago se ha abierto
`checkout.payment_page_opened`	La página de pago se ha mostrado
`checkout.customer_details_submitted`	Los detalles del cliente y de facturación han sido enviados
`checkout.closed`	La superposición de pago se ha cerrado
`checkout.redirect`	El pago realizará una redirección
`checkout.error`	Ocurrió un error durante el pago
`checkout.link_expired`	Se activa cuando la sesión de pago expira. Solo se recibe cuando `showTimer` está configurado en `false`.
`checkout.status`	Se activa cuando `manualRedirect` está habilitado. Contiene el estado del pago (`succeeded`, `failed`, o `processing`).
`checkout.redirect_requested`	Se activa cuando `manualRedirect` está habilitado. Contiene la URL a la que redirigir al cliente.

Opciones de Implementación

Instalación a través de 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 CDN

Para una integración rápida sin un paso de construcción, puedes usar nuestra 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 pago pasando un objeto themeConfig en el parámetro options al abrir el pago. La configuración del tema admite modos claros y oscuros, permitiéndote personalizar colores, bordes, texto, botones y radio de borde.

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 del 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 utilizará 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,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Tipos de TypeScript

Para usuarios de TypeScript, todos los tipos de configuración del tema están exportados:

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 sobre errores a través del sistema de eventos. Siempre implementa un manejo de errores adecuado en tu función de 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 pago
Manejo de errores: Siempre implementa un manejo de errores adecuado en tu función de 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 pago válidas de la API de crear sesión de pago
TypeScript: Usa TypeScript para una mejor seguridad de tipos y experiencia de desarrollador
Estados de carga: Muestra estados de carga mientras se abre el pago para mejorar la experiencia de usuario
Redirecciones manuales: Usa manualRedirect cuando necesites control personalizado sobre la navegación posterior al pago
Manejo de temporizadores: Desactiva el temporizador (showTimer: false) si deseas manejar la expiración de la sesión manualmente

Solución de Problemas

El checkout no se abre

Causas posibles:

SDK no inicializado antes de llamar a open()
URL de pago no vá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 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

Eventos no se disparan

Causas posibles:

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

Soluciones:

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

Problemas de estilo

Causas posibles:

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

Soluciones:

Revisa si hay conflictos de CSS en las herramientas de desarrollo del navegador
Verifica que las configuraciones del tema sean correctas
Prueba en diferentes tamaños de pantalla
Asegúrate de que no haya conflictos de z-index con la superposición

Activando Monederos Digitales

Para obtener información detallada sobre cómo configurar Apple Pay, Google Pay y otros monederos digitales, consulte la página de Monederos Digitales.

Configuración Rápida para Apple Pay

Descargar archivo de asociación de dominio

Descargue el archivo de asociación de dominio de Apple Pay.

Solicitar activación

Envíe un correo electrónico a support@dodopayments.com con la URL de su dominio de producción y solicite la activación de Apple Pay.

Probar después de la confirmación

Una vez confirmado, verifique que Apple Pay aparezca en el proceso de pago y pruebe el flujo completo.

Apple Pay requiere verificación de dominio antes de que aparezca en producción. Contacte al soporte antes de hacer el lanzamiento si planea ofrecer Apple Pay.

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+

Pago en Superposición vs Pago en Línea

Elija el tipo de pago adecuado para su caso de uso:

Característica	Pago en Superposición	Pago en Línea
Profundidad de integración	Modal sobre la página	Totalmente incrustado en la página
Control de diseño	Limitado	Control total
Branding	Separado de la página	Sin problemas
Esfuerzo de implementación	Menor	Mayor
Mejor para	Integración rápida, páginas existentes	Páginas de pago personalizadas, flujos de alta conversión

Utilice pago en superposición para una integración más rápida con cambios mínimos en sus páginas existentes. Use pago en línea cuando desee el máximo control sobre la experiencia de pago y branding sin problemas.

Recursos Relacionados

Pago en Línea

Incruste el pago directamente en su página para experiencias totalmente integradas.

API de Sesiones de Pago

Cree sesiones de pago para potenciar sus experiencias de pago.

Webhooks

Maneje eventos de pago del lado del servidor con webhooks.

Guía de Integración

Guía completa para integrar Dodo Payments.

Para más ayuda, visite nuestra comunidad de Discord o contacte a nuestro equipo de soporte para desarrolladores.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Descripción general

​Demostración

Demostración Interactiva

​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 Pago

​Verificar Estado

​Eventos

​Datos del Evento de Estado de Pago

​Datos del Evento de Redirección de Pago Solicitada

​Opciones de Implementación

​Instalación a través de Gestor de Paquetes

​Implementación 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

​Activando Monederos Digitales

​Configuración Rápida para Apple Pay

​Soporte de Navegadores

​Pago en Superposición vs Pago en Línea

​Recursos Relacionados

Pago en Línea

API de Sesiones de Pago

Webhooks

Guía de Integración

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 Pago

Verificar Estado

Eventos

Datos del Evento de Estado de Pago

Datos del Evento de Redirección de Pago Solicitada

Opciones de Implementación

Instalación a través de Gestor de Paquetes

Implementación 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

Activando Monederos Digitales

Configuración Rápida para Apple Pay

Soporte de Navegadores

Pago en Superposición vs Pago en Línea

Recursos Relacionados