Overlay Checkout - Dodo Payments Documentation

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.

Demo

Interactive Demo

See the overlay checkout in action with our live demo.

Quick Start

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

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

Get your checkout URL from the create checkout session API.

Step-by-Step Integration Guide

Install the SDK

Install the Dodo Payments Checkout SDK using your preferred package manager:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Initialize the SDK in your application, typically in your main component or app entry point:

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

Always initialize the SDK before attempting to open the checkout. Initialization should happen once when your application loads.

Create a Checkout Button Component

Create a component that opens the checkout overlay:

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

Use the checkout button component in your application:

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

Create pages to handle checkout redirects:

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

Start your development server:

npm run dev

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

You should see checkout events logged in your browser console.

Go Live

When you’re ready for production:

Change the mode to 'live':

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

Update your checkout URLs to use live checkout sessions from your backend
Test the complete flow in production
Monitor events and errors

API Reference

Configuration

Initialize Options

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

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

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

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

Fechar Checkout

Fecha programaticamente o overlay de checkout.

DodoPayments.Checkout.close();

Verificar Status

Retorna se o overlay de checkout está atualmente aberto.

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:

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.

Implementação via CDN

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

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.

A opção themeConfig no lado do cliente está obsoleta e será removida na próxima versão principal do Checkout SDK (v2.0.0). Usá-la gera um aviso de obsolescência no console do navegador. Em vez disso, configure seu tema ao criar a sessão de checkout por meio da API, usando o parâmetro customization.theme_config — consulte Personalização do tema do Checkout — ou visualmente na página Design do dashboard. Os temas configurados na sessão se aplicam igualmente ao checkout em overlay, inline e hospedado.

Esta seção aborda a configuração de tema no lado do cliente obsoleta usando o Checkout SDK. A abordagem recomendada é configurar os temas no lado do servidor ao criar uma sessão de checkout por meio da API, usando o parâmetro theme_config. Consulte Personalização do tema do Checkout para saber mais sobre a configuração no nível da API ou use a página Design no dashboard para configurar os temas visualmente com uma prévia em tempo real.

Configuração básica do 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",
    },
  },
});

Configuração completa do tema

Todas as propriedades de tema disponíveis:

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 quiser personalizar apenas o tema claro:

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 quiser personalizar apenas o tema escuro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Substituição parcial do tema

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

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 do tema com outras opções

Você pode combinar a configuração do tema com outras opções de checkout:

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:

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 sobre erros por meio do sistema de eventos. Sempre implemente o tratamento adequado de erros no seu 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");
    }
  }
});

Sempre trate o evento checkout.error para proporcionar uma boa experiência ao usuário quando ocorrerem erros.

Práticas recomendadas

Inicialize uma vez: inicialize o SDK uma vez quando o aplicativo for carregado, não a cada tentativa de checkout
Tratamento de erros: sempre implemente o tratamento adequado de erros no seu callback de evento
Modo de teste: use o modo test durante o desenvolvimento e alterne para live somente quando estiver pronto para produção
Tratamento de eventos: trate todos os eventos relevantes para proporcionar uma experiência completa ao usuário
URLs válidas: sempre use URLs de checkout válidas da API de criação de sessão de checkout
TypeScript: use TypeScript para obter mais segurança de tipos e uma melhor experiência de desenvolvimento
Estados de carregamento: mostre estados de carregamento enquanto o checkout estiver sendo aberto para melhorar a UX
Gerenciamento do temporizador: desative o temporizador (showTimer: false) se quiser tratar manualmente a expiração da sessão

Solução de problemas

Checkout not opening

Possíveis causas:

SDK não inicializado antes da chamada a 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 se há erros no console
Certifique-se de que a URL de checkout é válida e vem da API de criação de sessão de checkout
Verifique a conectividade de rede

Events not firing

Possíveis causas:

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

Soluções:

Confirme se o manipulador de eventos está configurado corretamente em Initialize()
Verifique se há erros de JavaScript no console do navegador
Verifique se a inicialização do SDK foi concluída com sucesso
Primeiro, teste com um manipulador de eventos simples

Styling issues

Possíveis causas:

Conflitos de CSS com os estilos do seu aplicativo
Configurações de tema não aplicadas corretamente
Problemas de design responsivo

Soluções:

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

Ativação de carteiras digitais

Para obter informações detalhadas sobre como configurar o Google Pay e outras carteiras digitais, consulte a página Carteiras digitais.

O Apple Pay ainda não é compatível com o checkout em overlay. O suporte ao Apple Pay estará disponível em breve.

Suporte a navegadores

O Dodo Payments Checkout SDK é compatível com os seguintes navegadores:

Chrome (mais recente)
Firefox (mais recente)
Safari (mais recente)
Edge (mais recente)
IE11+

Checkout em overlay vs. inline

Escolha o tipo de checkout adequado ao seu caso de uso:

Recurso	Checkout em overlay	Checkout inline
Profundidade da integração	Modal sobre a página	Totalmente incorporado à página
Controle do layout	Limitado	Controle total
Branding	Separado da página	Integrado
Esforço de implementação	Menor	Maior
Ideal para	Integração rápida, páginas existentes	Páginas de checkout personalizadas, fluxos de alta conversão

Use o checkout em overlay para uma integração mais rápida, com o mínimo de alterações nas páginas existentes. Use o checkout inline quando quiser o máximo de controle sobre a experiência de checkout e um branding integrado.

Recursos relacionados

Inline Checkout

Incorpore o checkout diretamente à sua página para obter experiências totalmente integradas.

Checkout Sessions API

Crie sessões de checkout para viabilizar suas experiências de checkout.

Webhooks

Trate eventos de pagamento no lado do servidor com webhooks.

Integration Guide

Guia completo para integrar o Dodo Payments.

Para obter mais ajuda, visite nossa comunidade no Discord ou entre em contato com nossa equipe de suporte para desenvolvedores.

​Overview

​Demo

Interactive Demo

​Quick Start

​Step-by-Step Integration Guide

​API Reference

​Configuration

​Initialize Options

​Checkout Options

​Methods

​Open Checkout

​Fechar Checkout

​Verificar Status

​Eventos

​Opções de Implementação

​Instalação via Gerenciador de Pacotes

​Implementação via CDN

​Customização de Tema

​Configuração básica do tema

​Configuração completa do tema

​Apenas modo claro

​Apenas modo escuro

​Substituição parcial do tema

​Configuração do tema com outras opções

​Tipos do TypeScript

​Tratamento de erros

​Práticas recomendadas

​Solução de problemas

​Ativação de carteiras digitais

​Suporte a navegadores

​Checkout em overlay vs. inline

​Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Overview

Demo

Quick Start

Step-by-Step Integration Guide

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

Fechar Checkout

Verificar Status

Eventos

Opções de Implementação

Instalação via Gerenciador de Pacotes

Implementação via CDN

Customização de Tema

Configuração básica do tema

Configuração completa do tema

Apenas modo claro

Apenas modo escuro

Substituição parcial do tema

Configuração do tema com outras opções

Tipos do TypeScript

Tratamento de erros

Práticas recomendadas

Solução de problemas

Ativação de carteiras digitais

Suporte a navegadores

Checkout em overlay vs. inline

Recursos relacionados