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

<Info>
  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](/features/checkout#checkout-theme-customization) para configuración a nivel de API, o usa la [página de Diseño](/features/design) en el panel para configurar temas visualmente con una vista previa en vivo.
</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 de tema disponibles:

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

#### Sobrescritura Parcial del Tema

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

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

```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>
  Siempre maneja el evento `checkout.error` para proporcionar una buena experiencia de usuario cuando ocurren errores.
</Warning>

## Mejores Prácticas

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

## Solución de Problemas

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

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

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

## 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 <a href="/features/payment-methods/digital-wallets">Carteras Digitales</a>.

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

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

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

## Recursos Relacionados

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

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

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Maneja eventos de pago del lado del servidor con 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 contacta a nuestro equipo de soporte para desarrolladores.