Overlay Checkout

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.

Modal de overlay checkout exibido sobre uma página de produto

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

Install the SDK

Instale via npm, yarn ou pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

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.

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

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

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

Test Your Integration

Inicie seu servidor de desenvolvimento:

npm run dev

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.

Go Live

Quando estiver pronto para produção:

Altere o modo para 'live':

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

Atualize suas URLs de checkout para usar sessões de checkout em produção do seu backend
Teste o fluxo completo em produção
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

Inicialize uma vez: chame Initialize uma vez quando seu app for carregado, não antes de cada checkout
Tratamento de erros: implemente o tratamento adequado de erros no seu callback de eventos
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 uma experiência completa do usuário
URLs válidas: sempre use URLs de checkout válidas da API create checkout session
TypeScript: use TypeScript para obter maior segurança de tipos e uma melhor experiência de desenvolvimento
Estados de carregamento: exiba estados de carregamento enquanto o checkout estiver abrindo para melhorar a UX
Gerenciamento do timer: desative o timer (showTimer: false) se quiser gerenciar manualmente a expiração da sessão

Solução de problemas

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Início rápido

Integração passo a passo

Referência da API

Inicializar

Abrir checkout

Fechar checkout

Verificar status

Eventos

Implementação via CDN

Personalização do tema

Propriedades do tema

Tratamento de erros

Práticas recomendadas

Solução de problemas

Carteiras digitais

Compatibilidade com navegadores

Overlay versus inline checkout

Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Início rápido

​Integração passo a passo

​Referência da API

​Inicializar

​Abrir checkout

​Fechar checkout

​Verificar status

​Eventos

​Implementação via CDN

​Personalização do tema

​Propriedades do tema

​Tratamento de erros

​Práticas recomendadas

​Solução de problemas

​Carteiras digitais

​Compatibilidade com navegadores

​Overlay versus inline checkout

​Recursos relacionados

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Início rápido

Integração passo a passo

Referência da API

Inicializar

Abrir checkout

Fechar checkout

Verificar status

Eventos

Implementação via CDN

Personalização do tema

Propriedades do tema

Tratamento de erros

Práticas recomendadas

Solução de problemas

Carteiras digitais

Compatibilidade com navegadores

Overlay versus inline checkout

Recursos relacionados