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

# Overlay Checkout

> A modern TypeScript library for embedding Dodo Payments overlay checkout and listening to checkout events in real-time.

## Overview

The Dodo Payments Checkout SDK provides a seamless way to integrate our payment overlay into your web application. Built with TypeScript and modern web standards, it offers a robust solution for handling payments with real-time event handling and customizable themes.

<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="Overlay Checkout Cover Image" style={{ maxHeight: '500px', width: 'auto' }} width="3826" height="2160" data-path="images/cover-images/overlay-checkout.png" />
</Frame>

## Demo

<Card title="Interactive Demo" icon="play" href="https://atlas.dodopayments.com/pricing">
  See the overlay checkout in action with our live demo.
</Card>

## Quick Start

Get started with the Dodo Payments Checkout SDK in just a few lines of code:

```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>
  Get your checkout URL from the [create checkout session API](/api-reference/checkout-sessions/create).
</Tip>

## Step-by-Step Integration Guide

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Checkout SDK using your preferred package manager:

    <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">
    Initialize the SDK in your application, typically in your main component or app entry point:

    ```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>
      Always initialize the SDK before attempting to open the checkout. Initialization should happen once when your application loads.
    </Warning>
  </Step>

  <Step title="Create a Checkout Button Component">
    Create a component that opens the checkout overlay:

    ```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">
    Use the checkout button component in your application:

    ```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">
    Create pages to handle checkout redirects:

    ```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. Start your development server:

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

    2. Test the checkout flow:
       * Click the checkout button
       * Verify the overlay appears
       * Test the payment flow using test credentials
       * Confirm redirects work correctly

    <Check>
      You should see checkout events logged in your browser console.
    </Check>
  </Step>

  <Step title="Go Live">
    When you're ready for production:

    1. Change the mode to `'live'`:

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

    2. Update your checkout URLs to use live checkout sessions from your backend
    3. Test the complete flow in production
    4. Monitor events and errors
  </Step>
</Steps>

## API Reference

### Configuration

#### Initialize Options

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

#### Checkout Options

```typescript theme={null}
interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}
```

| Opção                       | Tipo      | Obrigatório | Descrição                                                                                                                                                    |
| --------------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `checkoutUrl`               | `string`  | Sim         | URL da sessão de checkout da [API de criação de sessão de checkout](/api-reference/checkout-sessions/create)                                                 |
| `options.showTimer`         | `boolean` | Não         | Mostrar ou ocultar o temporizador de checkout. O padrão é `true`. Quando desativado, você receberá o evento `checkout.link_expired` quando a sessão expirar. |
| `options.showSecurityBadge` | `boolean` | Não         | Mostrar ou ocultar o badge de segurança. O padrão é `true`.                                                                                                  |

### Methods

#### Open Checkout

Opens the checkout overlay with the specified checkout session URL.

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

You can also pass additional options to customize the checkout behavior:

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

#### Fechar Checkout

Fecha programaticamente o overlay de checkout.

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

#### Verificar Status

Retorna se o overlay de checkout está atualmente aberto.

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

### Eventos

O SDK fornece eventos em tempo real aos quais você pode ouvir através do 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                        | Descrição                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `checkout.opened`                     | Overlay de checkout foi aberto                                                                                   |
| `checkout.form_ready`                 | Formulário de checkout está pronto para receber a entrada do usuário. Útil para ocultar estados de carregamento. |
| `checkout.payment_page_opened`        | Página de pagamento foi exibida                                                                                  |
| `checkout.customer_details_submitted` | Detalhes do cliente e de cobrança foram submetidos                                                               |
| `checkout.closed`                     | Overlay de checkout foi fechado                                                                                  |
| `checkout.redirect`                   | Checkout realizará um redirecionamento                                                                           |
| `checkout.error`                      | Ocorreu um erro durante o checkout                                                                               |
| `checkout.link_expired`               | Acionado quando a sessão de checkout expira. Somente recebido quando `showTimer` é definido para `false`.        |

## Opções de Implementação

### Instalação via Gerenciador de Pacotes

Instale via npm, yarn ou pnpm conforme mostrado no [Guia de Integração Passo a Passo](#step-by-step-integration-guide).

### Implementação via CDN

Para integração rápida sem uma etapa de build, você pode usar nosso 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>
```

### Customização de Tema

Você pode personalizar a aparência do checkout passando um objeto `themeConfig` no parâmetro `options` ao abrir o checkout. A configuração do tema suporta modos claro e escuro, permitindo que você personalize cores, bordas, texto, botões e raio das bordas.

<Info>
  Esta seção cobre a configuração de tema **client-side** usando o Checkout SDK. Você também pode configurar temas **server-side** ao criar uma sessão de checkout via API usando o parâmetro `theme_config`. Veja [Customização de Tema do Checkout](/features/checkout#checkout-theme-customization) para configuração a nível de API, ou use a [página Design](/features/design) no painel para configurar temas visualmente com visualização ao vivo.
</Info>

#### Configuração Básica de 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",
    },
  },
});
```

#### Configuração Completa de Tema

Todas as propriedades de tema disponíveis:

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

#### Apenas Modo Claro

Se você deseja personalizar apenas o 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",
    },
  },
});
```

#### Apenas Modo Escuro

Se você deseja personalizar apenas o tema escuro:

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

#### Sobrescrita Parcial de Tema

Você pode sobrescrever apenas propriedades específicas. O checkout usará valores padrão para propriedades que você não especificar:

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

#### Configuração de Tema com Outras Opções

Você pode combinar a configuração de tema com outras opções 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 do TypeScript

Para usuários do TypeScript, todos os tipos de configuração de tema são exportados:

```typescript theme={null}
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};
```

## Tratamento de Erros

O SDK fornece informações detalhadas de erro através do sistema de eventos. Sempre implemente o tratamento adequado de erros no seu 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>
  Sempre trate o evento `checkout.error` para fornecer uma boa experiência ao usuário quando ocorrerem erros.
</Warning>

## Melhores Práticas

1. **Inicialize uma vez**: Inicialize o SDK uma vez quando sua aplicação carregar, não a cada tentativa de checkout
2. **Tratamento de erros**: Sempre implemente o tratamento adequado de erros no seu callback de eventos
3. **Modo de teste**: Use o modo `test` durante o desenvolvimento e altere para `live` apenas quando estiver pronto para produção
4. **Tratamento de eventos**: Trate todos os eventos relevantes para uma experiência completa do usuário
5. **URLs válidas**: Sempre use URLs de checkout válidas da API de criação de sessão de checkout
6. **TypeScript**: Use TypeScript para melhor segurança de tipos e experiência do desenvolvedor
7. **Estados de carregamento**: Mostre estados de carregamento enquanto o checkout é aberto para melhorar a UX
8. **Gestão de temporizador**: Desative o temporizador (`showTimer: false`) se você quiser lidar com a expiração da sessão manualmente

## Solução de Problemas

<AccordionGroup>
  <Accordion title="Checkout not opening">
    **Possíveis causas:**

    * SDK não inicializado antes de chamar `open()`
    * URL de checkout inválida
    * Erros de JavaScript no console
    * Problemas de conectividade de rede

    **Soluções:**

    * Verifique se a inicialização do SDK ocorre antes de abrir o checkout
    * Verifique erros no console
    * Certifique-se de que a URL de checkout é válida e da API de criação de sessão de checkout
    * Verifique a conectividade de rede
  </Accordion>

  <Accordion title="Events not firing">
    **Possíveis causas:**

    * Manipulador de eventos não configurado corretamente
    * Erros de JavaScript impedindo a propagação do evento
    * SDK não inicializado corretamente

    **Soluções:**

    * Confirme se o manipulador de eventos está configurado corretamente em `Initialize()`
    * Verifique o console do navegador para erros de JavaScript
    * Verifique se a inicialização do SDK foi concluída com sucesso
    * Teste com um manipulador de eventos simples primeiro
  </Accordion>

  <Accordion title="Styling issues">
    **Possíveis causas:**

    * Conflitos de CSS com os estilos da sua aplicação
    * Configurações de tema não aplicadas corretamente
    * Problemas de design responsivo

    **Soluções:**

    * Verifique conflitos de CSS no DevTools do navegador
    * Verifique se as configurações de tema estão corretas
    * Teste em diferentes tamanhos de tela
    * Certifique-se de que não há conflitos de z-index com o overlay
  </Accordion>
</AccordionGroup>

## Ativando Carteiras Digitais

Para informações detalhadas sobre como configurar o Google Pay e outras carteiras digitais, veja a página de <a href="/features/payment-methods/digital-wallets">Carteiras Digitais</a>.

<Note>
  Apple Pay ainda não é suportado no overlay de checkout. Suporte para Apple Pay em breve.
</Note>

## Suporte a Navegadores

O SDK de Checkout Dodo Payments suporta os seguintes navegadores:

* Chrome (última versão)
* Firefox (última versão)
* Safari (última versão)
* Edge (última versão)
* IE11+

## Overlay vs Inline Checkout

Escolha o tipo de checkout certo para seu caso de uso:

| Recurso                    | Overlay Checkout                      | Inline Checkout                                              |
| -------------------------- | ------------------------------------- | ------------------------------------------------------------ |
| Profundidade de integração | Modal sobre a página                  | Totalmente integrado na página                               |
| Controle de layout         | Limitado                              | Controle total                                               |
| Branding                   | Separado da página                    | Sem costura                                                  |
| Esforço de implementação   | Menor                                 | Maior                                                        |
| Melhor para                | Integração rápida, páginas existentes | Páginas de checkout personalizadas, fluxos de alta conversão |

<Tip>
  Use **overlay checkout** para integração mais rápida com mínimas mudanças em suas páginas existentes. Use **inline checkout** quando quiser máximo controle sobre a experiência de checkout e branding contínuo.
</Tip>

## Recursos Relacionados

<CardGroup cols={2}>
  <Card title="Inline Checkout" icon="credit-card" href="/developer-resources/inline-checkout">
    Incorpore checkout diretamente na sua página para experiências totalmente integradas.
  </Card>

  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Crie sessões de checkout para potencializar suas experiências de checkout.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Lide com eventos de pagamento no lado do servidor usando webhooks.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Guia completo para integrar Dodo Payments.
  </Card>
</CardGroup>

Para mais ajuda, visite nossa [comunidade no Discord](https://discord.gg/bYqAp4ayYh) ou entre em contato com nossa equipe de suporte ao desenvolvedor.