> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pago en Superposición

> Una moderna biblioteca de TypeScript para incrustar el pago en superposición de Dodo Payments y escuchar eventos de pago en tiempo real.

## 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.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/cover-images/overlay-checkout.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=15d90c695e92914a9d54b10509d6fe47" alt="Imagen de portada del Checkout en Superposición" style={{ maxHeight: '500px', width: 'auto' }} width="3826" height="2160" data-path="images/cover-images/overlay-checkout.png" />
</Frame>

## Demostración

<Card title="Interactive Demo" icon="play" href="https://atlas.dodopayments.com/pricing">
  Vea el overlay checkout en acción con nuestra demostración en vivo.
</Card>

## Inicio Rápido

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

```typescript theme={null}
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"
});
```

<Tip>
  Obtén tu URL de checkout desde la [create checkout session API](/api-reference/checkout-sessions/create).
</Tip>

## Guía de Integración Paso a Paso

<Steps>
  <Step title="Install the SDK">
    Instale el SDK de Pago de Dodo Payments utilizando su gestor de paquetes preferido:

    <CodeGroup>
      ```bash npm theme={null}
      npm install dodopayments-checkout
      ```

      ```bash yarn theme={null}
      yarn add dodopayments-checkout
      ```

      ```bash pnpm theme={null}
      pnpm add dodopayments-checkout
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the SDK">
    Inicialice el SDK en su aplicación, típicamente en su componente principal o punto de entrada de la aplicación:

    ```typescript theme={null}
    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;
        }
      },
    });
    ```

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

  <Step title="Create a Checkout Button Component">
    Cree un componente que abra la superposición de pago:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Add Checkout to Your Page">
    Utilice el componente de botón de pago en su aplicación:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Handle Success and Failure Pages">
    Cree páginas para manejar redirecciones de pago:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Test Your Integration">
    1. Inicie su servidor de desarrollo:

    ```bash theme={null}
    npm run dev
    ```

    2. 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

    <Check>
      Deberías ver los eventos del checkout registrados en la consola del navegador.
    </Check>
  </Step>

  <Step title="Go Live">
    Cuando esté listo para producción:

    1. Cambia el modo a `'live'`:

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

    2. Actualice sus URLs de pago para usar sesiones de pago en vivo desde su backend
    3. Pruebe el flujo completo en producción
    4. Monitoree eventos y errores
  </Step>
</Steps>

## Referencia de API

### Configuración

#### Opciones de Inicialización

```typescript theme={null}
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

```typescript theme={null}
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](/api-reference/checkout-sessions/create)                                              |
| `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.

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
```

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

```typescript theme={null}
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.

```typescript theme={null}
DodoPayments.Checkout.close();
```

#### Verificar Estado

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

```typescript theme={null}
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean
```

### Eventos

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

```typescript theme={null}
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](#step-by-step-integration-guide).

### Implementación del CDN

Para una integración rápida sin un paso de construcción, puedes usar nuestro CDN:

```html theme={null}
<!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.

<Warning>
  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](/features/checkout#checkout-theme-customization) — o visualmente en la [página de diseño](/features/design) del dashboard. Los temas configurados en la sesión se aplican por igual al checkout overlay, inline y hosted.
</Warning>

<Info>
  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](/features/checkout#checkout-theme-customization) para la configuración a nivel de API, o usa la [página de diseño](/features/design) del dashboard para configurar los temas visualmente con una vista previa en tiempo real.
</Info>

#### Configuración básica del tema

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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");
    }
  }
});
```

<Warning>
  Gestiona siempre el evento `checkout.error` para ofrecer una buena experiencia de usuario cuando se produzcan errores.
</Warning>

## Prácticas recomendadas

1. **Inicializa una vez**: inicializa el SDK una vez cuando se cargue tu aplicación, no en cada intento de checkout
2. **Gestión de errores**: implementa siempre una gestión adecuada de errores en tu callback de eventos
3. **Modo de prueba**: usa el modo `test` durante el desarrollo y cambia a `live` solo cuando estés listo para producción
4. **Gestión de eventos**: gestiona todos los eventos relevantes para ofrecer una experiencia de usuario completa
5. **URLs válidas**: usa siempre URLs de checkout válidas provenientes de la API de creación de sesiones de checkout
6. **TypeScript**: usa TypeScript para mejorar la seguridad de tipos y la experiencia del desarrollador
7. **Estados de carga**: muestra estados de carga mientras se abre el checkout para mejorar la UX
8. **Gestión del temporizador**: desactiva el temporizador (`showTimer: false`) si quieres gestionar manualmente la expiración de la sesión

## Solución de problemas

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Habilitar billeteras digitales

Para obtener información detallada sobre la configuración de Google Pay y otras billeteras digitales, consulta la página de <a href="/features/payment-methods/digital-wallets">billeteras digitales</a>.

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

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

<Tip>
  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.
</Tip>

## Recursos relacionados

<CardGroup cols={2}>
  <Card title="Inline Checkout" icon="credit-card" href="/developer-resources/inline-checkout">
    Inserta el checkout directamente en tu página para ofrecer experiencias totalmente integradas.
  </Card>

  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Crea sesiones de checkout para impulsar tus experiencias de checkout.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Gestiona los eventos de pago del lado del servidor mediante webhooks.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Guía completa para integrar Dodo Payments.
  </Card>
</CardGroup>

Para obtener más ayuda, visita nuestra [comunidad de Discord](https://discord.gg/bYqAp4ayYh) o ponte en contacto con nuestro equipo de soporte para desarrolladores.