Overlay Checkout

Abra o checkout do Dodo Payments como um modal na sua página. O SDK de overlay checkout gerencia a coleta de pagamentos enquanto sua página permanece visível ao fundo.

O overlay checkout abre uma janela modal sobre a sua página. Os clientes inserem seus dados de pagamento no modal enquanto sua página permanece visível ao fundo. Quando fecham o modal, o controle retorna à sua página. Quando concluem o pagamento, são redirecionados para return_url.

Interactive Demo

Veja o overlay checkout em ação com nossa demonstração ao vivo.

​

Início rápido

Instale o SDK, inicialize-o e abra o checkout com uma URL de checkout da API create checkout session:

import { DodoPayments } from "dodopayments-checkout";

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

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

​

Integração passo a passo

1. Install the SDK

   Instale via npm, yarn ou pnpm:

   npm

   npm install dodopayments-checkout
   
2. Initialize the SDK

   Chame Initialize uma vez quando seu app for carregado, normalmente no componente principal ou no ponto de entrada do app:

   import { DodoPayments } from "dodopayments-checkout";
   
   DodoPayments.Initialize({
     mode: "test", // Change to 'live' for production
     displayType: "overlay",
     onEvent: (event) => {
       console.log("Checkout event:", event);
       
       switch (event.event_type) {
         case "checkout.opened":
           // Modal has opened
           break;
         case "checkout.closed":
           // Modal has closed
           break;
         case "checkout.error":
           console.error("Checkout error:", event.data?.message);
           break;
       }
     },
   });
   

   Sempre inicialize o SDK antes de abrir o checkout. Inicialize-o uma vez quando sua aplicação for carregada, não antes de cada tentativa de checkout.

3. Create a Checkout Button

   Crie um componente que abra o modal de checkout:

   // 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(() => {
       DodoPayments.Initialize({
         mode: "test",
         displayType: "overlay",
         onEvent: (event) => {
           if (event.event_type === "checkout.opened") {
             setIsLoading(false);
           }
           if (event.event_type === "checkout.error") {
             setIsLoading(false);
             console.error("Checkout error:", event.data?.message);
           }
         },
       });
     }, []);
   
     const handleCheckout = async () => {
       setIsLoading(true);
       try {
         await DodoPayments.Checkout.open({
           checkoutUrl: "https://test.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>
     );
   }
   
4. Add the Button to Your Page

   Use o componente do botão de checkout na sua aplicação:

   // 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>
     );
   }
   
5. Handle Redirects

   Crie páginas para gerenciar os redirecionamentos do checkout após o pagamento:

   // 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>
     );
   }
   
6. Test Your Integration

   1. Inicie seu servidor de desenvolvimento:

   npm run dev
   

   2. Teste o fluxo de checkout:
      • Clique no botão de checkout
      • Verifique se o modal aparece
      • Teste o fluxo de pagamento usando credenciais de teste
      • Confirme se os redirecionamentos funcionam corretamente

   Você deverá ver os eventos do checkout registrados no console do navegador.

7. Go Live

   Quando estiver pronto para produção:

   1. Altere o modo para 'live':

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

   2. Atualize suas URLs de checkout para usar sessões de checkout em produção do seu backend
   3. Teste o fluxo completo em produção
   4. Monitore eventos e erros

​

Referência da API

​

Inicializar

Chame Initialize uma vez para configurar o SDK:

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

Opção	Tipo	Obrigatório	Descrição
mode	"test" | "live"	Sim	Modo do ambiente: "test" para desenvolvimento, "live" para produção
displayType	"overlay" | "inline"	Não	Tipo de exibição: "overlay" para checkout modal (padrão), "inline" para checkout incorporado
onEvent	function	Sim	Função de callback para gerenciar eventos do checkout

​

Abrir checkout

Abra o modal de checkout:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Opção	Tipo	Obrigatório	Descrição
checkoutUrl	string	Sim	URL da sessão de checkout da API create checkout session
options.showTimer	boolean	Não	Exibe ou oculta o timer da sessão. O padrão é true. Quando desativado, você recebe o evento checkout.link_expired quando a sessão expira.
options.showSecurityBadge	boolean	Não	Exibe ou oculta o selo de segurança. O padrão é true
options.manualRedirect	boolean	Não	Quando true, impede redirecionamentos automáticos. O checkout emite checkout.status com o resultado do pagamento e checkout.redirect_requested com a URL a ser aberta, e você gerencia a navegação
options.themeConfig	ThemeConfig	Não	Obsoleto. Configure o tema no servidor ao criar a sessão de checkout
options.payButtonText	string	Não	Texto personalizado para o botão de pagamento
options.fontSize	"xs" | "sm" | "md" | "lg" | "xl" | "2xl"	Não	Tamanho global da fonte do checkout
options.fontWeight	"normal" | "medium" | "bold" | "extraBold"	Não	Peso global da fonte do checkout

​

Fechar checkout

Feche o modal programaticamente:

DodoPayments.Checkout.close();

​

Verificar status

Verifique se o modal está aberto no momento:

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

​

Eventos

Escute os eventos do checkout por meio do callback onEvent passado para Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Evento	Descrição
checkout.opened	O modal foi aberto
checkout.form_ready	O formulário está pronto para a entrada do usuário. Use isso para ocultar estados de carregamento
checkout.payment_page_opened	A página de pagamento está sendo exibida
checkout.customer_details_submitted	Dados do cliente e de cobrança enviados
checkout.closed	O modal foi fechado
checkout.redirect	O checkout será redirecionado (por exemplo, para uma página bancária)
checkout.error	Ocorreu um erro durante o checkout
checkout.link_expired	A sessão de checkout expirou. Recebido somente quando showTimer está definido como false.

​

Implementação via CDN

Para uma integração rápida sem uma etapa de build, carregue o SDK via 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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

​

Personalização do tema

A opção themeConfig de tema no lado do cliente está obsoleta e será removida na próxima versão principal do Checkout SDK (v2.0.0). Passá-la registra 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 overlay, ao inline e ao hosted checkout.

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 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 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 ao vivo.

Se precisar usar a configuração de tema no lado do cliente, passe themeConfig no parâmetro options:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

​

Propriedades do tema

Todas as propriedades de tema disponíveis para os modos claro e escuro:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

​

Tratamento de erros

Sempre implemente o tratamento 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);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

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

​

Práticas recomendadas

1. Inicialize uma vez: chame Initialize uma vez quando seu app for carregado, não antes de cada checkout
2. Tratamento de erros: implemente o tratamento adequado de erros no seu callback de eventos
3. Modo de teste: use o modo "test" durante o desenvolvimento e alterne para "live" somente 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 create checkout session
6. TypeScript: use TypeScript para obter maior segurança de tipos e uma melhor experiência de desenvolvimento
7. Estados de carregamento: exiba estados de carregamento enquanto o checkout estiver abrindo para melhorar a UX
8. Gerenciamento do timer: desative o timer (showTimer: false) se quiser gerenciar manualmente a expiração da sessão

​

Solução de problemas

Checkout modal not opening

Possíveis causas:

• O SDK não foi 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 da abertura do checkout
• Verifique se há erros no console do navegador
• Certifique-se de que a URL de checkout é válida e vem da API create checkout session
• Verifique a conectividade de rede

Events not firing

Possíveis causas:

• O manipulador de eventos não foi configurado corretamente
• Erros de JavaScript impedindo a propagação de eventos
• O SDK não foi 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
• Teste primeiro com um manipulador de eventos simples

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 se há conflitos de CSS no DevTools do navegador
• Confirme 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 modal

​

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 overlay checkout.

​

Compatibilidade com navegadores

O Checkout SDK do Dodo Payments é compatível com:

• Chrome (versão mais recente)
• Firefox (versão mais recente)
• Safari (versão mais recente)
• Edge (versão mais recente)
• IE11+

​

Overlay versus inline checkout

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

Recurso	Overlay	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	Corresponde à sua página
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 overlay checkout para uma integração mais rápida, com alterações mínimas nas suas páginas existentes. Use o inline checkout quando quiser máximo controle sobre a experiência de checkout e um branding consistente.

​

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

Gerencie eventos de pagamento no 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.