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.

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

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;
    manualRedirect?: boolean;
  };
}

Option	Type	Required	Description
`checkoutUrl`	`string`	Yes	Checkout session URL from the create checkout session API
`options.showTimer`	`boolean`	No	Show or hide the checkout timer. Defaults to `true`. When disabled, you will receive the `checkout.link_expired` event when the session expires.
`options.showSecurityBadge`	`boolean`	No	Show or hide the security badge. Defaults to `true`.
`options.manualRedirect`	`boolean`	No	When enabled, the checkout will not automatically redirect after completion. Instead, you will receive `checkout.status` and `checkout.redirect_requested` events to handle the redirect yourself.

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

Cuando uses manualRedirect, maneja la finalización del checkout en tu 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 mediante el 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.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;
      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;
    }
  }
});

Event Type	Description
`checkout.opened`	Se ha abierto la superposición de checkout
`checkout.form_ready`	El formulario de checkout está listo para recibir los datos del usuario. Útil para ocultar estados de carga.
`checkout.payment_page_opened`	Se ha mostrado la página de pago
`checkout.customer_details_submitted`	Se han enviado los datos del cliente y de facturación
`checkout.closed`	Se ha cerrado la superposición de checkout
`checkout.redirect`	El checkout realizará una redirección
`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á establecido en `false`.
`checkout.status`	Se dispara cuando `manualRedirect` está habilitado. Contiene el estado del checkout (`succeeded`, `failed` o `processing`).
`checkout.redirect_requested`	Se dispara cuando `manualRedirect` está habilitado. Contiene la URL para 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 checkout pasando un objeto themeConfig en el parámetro options al abrir el checkout. La configuración del tema admite los modos claro y oscuro, permitiéndote personalizar los colores, bordes, texto, botones y el radio de los bordes.

Esta sección cubre la configuración de temas del lado del cliente mediante el SDK de Checkout. También puedes configurar los temas del lado del servidor al crear una sesión de pago a través de la API usando el parámetro theme_config. Consulta Checkout Theme Customization para la configuración a nivel de API, o utiliza la página de diseño en el panel para configurar los temas visualmente con 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",
    },
  },
});

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

Tipos de TypeScript

Para los 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 mediante el 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 ofrecer una buena experiencia al usuario cuando ocurran errores.

Mejores prácticas

Inicializa una sola vez: inicializa el SDK una sola vez cuando se carga tu aplicación, no en cada intento de checkout
Manejo de errores: siempre implementa un manejo apropiado 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: atiende todos los eventos relevantes para ofrecer una experiencia completa al usuario
URLs válidas: siempre usa URLs de checkout válidas provenientes de la API create checkout session
TypeScript: usa TypeScript para una mejor seguridad de tipos y experiencia de desarrollo
Estados de carga: muestra estados de carga mientras se abre el checkout para mejorar la experiencia del usuario
Redirecciones manuales: usa manualRedirect cuando necesites control personalizado sobre la navegación posterior al checkout
Gestión del temporizador: deshabilita el temporizador (showTimer: false) si deseas manejar manualmente la expiración de la sesión

Resolución de problemas

Checkout not opening

Posibles causas:

El SDK no se inicializó 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 si hay errores en la consola
Asegúrate de que la URL de checkout sea válida y provenga de la API create checkout session
Verifica la conectividad de red

Events not firing

Posibles causas:

El manejador 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 manejador de eventos esté configurado correctamente en Initialize()
Revisa 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

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:

Revisa conflictos de CSS en las herramientas de desarrollo 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 billeteras digitales

Para obtener información detallada sobre cómo configurar Google Pay y otras billeteras digitales, consulta la página de Digital Wallets.

Apple Pay aún no es compatible con el overlay checkout. El soporte para Apple Pay llegará pronto.

Compatibilidad con navegadores

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

Chrome (última)
Firefox (última)
Safari (última)
Edge (última)
IE11+

Overlay vs Checkout en línea

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

Función	Overlay Checkout	Inline Checkout
Profundidad de integración	Modal encima de la página	Completamente integrado en la página
Control del diseño	Limitado	Control total
Branding	Separado de la página	Sin fisuras
Esfuerzo de implementación	Menor	Mayor
Ideal para	Integraciones rápidas y páginas existentes	Páginas de checkout personalizadas y flujos de 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 necesites el máximo control sobre la experiencia de checkout y un branding fluido.

Recursos relacionados

Inline Checkout

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

Checkout Sessions API

Crea sesiones de checkout para impulsar tus experiencias de pago.

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

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

​Anulación parcial del tema

​Configuración del tema con otras opciones

​Tipos de TypeScript

​Manejo de errores

​Mejores prácticas

​Resolución de problemas

​Activación de billeteras digitales

​Compatibilidad con navegadores

​Overlay vs Checkout en línea

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

Anulación parcial del tema

Configuración del tema con otras opciones

Tipos de TypeScript

Manejo de errores

Mejores prácticas

Resolución de problemas

Activación de billeteras digitales

Compatibilidad con navegadores

Overlay vs Checkout en línea

Recursos relacionados