Overlay Checkout - Dodo Payments Documentation

Visão Geral

O SDK de Checkout do Dodo Payments fornece uma maneira perfeita de integrar nosso overlay de pagamento em sua aplicação web. Construído com TypeScript e padrões modernos da web, oferece uma solução robusta para lidar com pagamentos com manipulação de eventos em tempo real e temas personalizáveis.

Demonstração

Demonstração Interativa

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

Começo Rápido

Comece com o SDK de Checkout do Dodo Payments em apenas algumas linhas de código:

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

Obtenha sua URL de checkout na API de criação de sessão de checkout.

Guia de Integração Passo a Passo

Instalar o SDK

Instale o SDK de Checkout do Dodo Payments usando seu gerenciador de pacotes preferido:

npm install dodopayments-checkout

Inicializar o SDK

Inicialize o SDK em sua aplicação, tipicamente em seu componente principal ou ponto de entrada do app:

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

Sempre inicialize o SDK antes de tentar abrir o checkout. A inicialização deve ocorrer uma vez quando sua aplicação carrega.

Criar um Componente de Botão de Checkout

Crie um componente que abre o overlay 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(() => {
    // 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>
  );
}

Adicionar Checkout à Sua Página

Use o componente de botão de checkout em 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>
  );
}

Gerenciar Páginas de Sucesso e Falha

Crie páginas para gerenciar redirecionamentos de checkout:

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

Teste Sua Integração

Inicie seu servidor de desenvolvimento:

npm run dev

Teste o fluxo de checkout:
- Clique no botão de checkout
- Verifique se o overlay aparece
- Teste o fluxo de pagamento usando credenciais de teste
- Confirme se os redirecionamentos funcionam corretamente

Você deve ver eventos de checkout registrados no console do seu navegador.

Ir para Produção

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 ao vivo do seu backend
Teste o fluxo completo em produção
Monitore eventos e erros

Referência da API

Configuração

Opções de Inicialização

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

Opção	Tipo	Necessário	Descrição
`mode`	`"test" \| "live"`	Sim	Modo de 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 embutido
`onEvent`	`function`	Sim	Função de callback para manipular eventos de checkout

Opções de Checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

Opção	Tipo	Necessá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 distintivo de segurança. O padrão é `true`.
`options.manualRedirect`	`boolean`	Não	Quando habilitado, o checkout não redirecionará automaticamente após a conclusão. Em vez disso, você receberá os eventos `checkout.status` e `checkout.redirect_requested` para gerenciar o redirecionamento você mesmo.

Métodos

Abrir Checkout

Abre o overlay de checkout com a URL da sessão de checkout especificada.

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

Você também pode passar opções adicionais para personalizar o comportamento do checkout:

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

Ao usar manualRedirect, manipule a conclusão do checkout em seu callback de onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Fechar Checkout

Fecha programaticamente a sobreposição de checkout.

DodoPayments.Checkout.close();

Verificar Status

Retorna se a sobreposição de checkout está atualmente aberta.

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

Eventos

O SDK fornece eventos em tempo real que você pode ouvir através do callback de onEvent:

Dados do Evento de Status do Checkout

Quando manualRedirect está habilitado, você recebe o evento checkout.status com os seguintes dados:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Dados do Evento de Redirecionamento do Checkout Solicitado

Quando manualRedirect está habilitado, você recebe o evento checkout.redirect_requested com os seguintes dados:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        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;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Tipo de Evento	Descrição
`checkout.opened`	A sobreposição de checkout foi aberta
`checkout.payment_page_opened`	A página de pagamento foi exibida
`checkout.customer_details_submitted`	Detalhes do cliente e de cobrança foram enviados
`checkout.closed`	A sobreposição de checkout foi fechada
`checkout.redirect`	O checkout realizará um redirecionamento
`checkout.error`	Ocorreu um erro durante o checkout
`checkout.link_expired`	Disparado quando a sessão de checkout expira. Recebido apenas quando `showTimer` está definido como `false`.
`checkout.status`	Disparado quando `manualRedirect` está habilitado. Contém o status do checkout (`succeeded`, `failed`, ou `processing`).
`checkout.redirect_requested`	Disparado quando `manualRedirect` está habilitado. Contém a URL para redirecionar o cliente.

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 CDN

Para uma integração rápida sem uma etapa de construção, 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>

Personalizaçã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 de borda.

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

Somente Modo Claro

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

Somente Modo Escuro

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

Sobrescrita Parcial do Tema

Você pode sobrescrever apenas propriedades específicas. O checkout usará valores padrão para 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,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Tipos TypeScript

Para usuários 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 através do sistema de eventos. Sempre implemente um tratamento de erros adequado em seu callback de 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 erros ocorrerem.

Melhores Práticas

Inicialize uma vez: Inicialize o SDK uma vez quando seu aplicativo carregar, não em cada tentativa de checkout
Tratamento de erros: Sempre implemente um tratamento de erros adequado em seu callback de evento
Modo de teste: Use o modo test durante o desenvolvimento e mude para live apenas 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 de criação de sessão de checkout
TypeScript: Use TypeScript para melhor segurança de tipos e experiência do desenvolvedor
Estados de carregamento: Mostre estados de carregamento enquanto o checkout está sendo aberto para melhorar a experiência do usuário
Redirecionamentos manuais: Use manualRedirect quando precisar de controle personalizado sobre a navegação pós-checkout
Gerenciamento de temporizador: Desative o temporizador (showTimer: false) se você quiser gerenciar a expiração da sessão manualmente

Solução de Problemas

Checkout não abrindo

Causas possíveis:

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

Eventos não disparando

Causas possíveis:

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

Soluções:

Confirme que 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 primeiro com um manipulador de eventos simples

Problemas de estilo

Causas possíveis:

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 de tema estão corretas
Teste em diferentes tamanhos de tela
Certifique-se de que não há conflitos de z-index com sobreposições

Habilitando Carteiras Digitais

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

Configuração Rápida para Apple Pay

Baixar o arquivo de associação de domínio

Baixe o arquivo de associação de domínio do Apple Pay.

Solicitar ativação

Envie um e-mail para support@dodopayments.com com a URL do seu domínio de produção e solicite a ativação do Apple Pay.

Teste após confirmação

Uma vez confirmado, verifique se o Apple Pay aparece no checkout e teste o fluxo completo.

O Apple Pay requer verificação de domínio antes de aparecer em produção. Entre em contato com o suporte antes de ir ao vivo se você planeja oferecer Apple Pay.

Suporte a Navegadores

O SDK de Checkout da Dodo Payments suporta os seguintes navegadores:

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

Checkout em Sobreposição vs Inline

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

Recurso	Checkout em Sobreposição	Checkout Inline
Profundidade da Integração	Modal sobre a página	Totalmente embutido 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

Use o checkout em sobreposição para uma integração mais rápida com mínimas mudanças em suas páginas existentes. Use o checkout inline quando quiser controle máximo sobre a experiência de checkout e branding sem costuras.

Recursos Relacionados

Checkout Inline

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

API de Sessões de Checkout

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

Webhooks

Gerencie eventos de pagamento no lado do servidor com webhooks.

Guia de Integração

Guia completo para integrar a Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Visão Geral

​Demonstração

Demonstração Interativa

​Começo Rápido

​Guia de Integração Passo a Passo

​Referência da API

​Configuração

​Opções de Inicialização

​Opções de Checkout

​Métodos

​Abrir Checkout

​Fechar Checkout

​Verificar Status

​Eventos

​Dados do Evento de Status do Checkout

​Dados do Evento de Redirecionamento do Checkout Solicitado

​Opções de Implementação

​Instalação via Gerenciador de Pacotes

​Implementação CDN

​Personalização de Tema

​Configuração Básica do Tema

​Configuração Completa do Tema

​Somente Modo Claro

​Somente Modo Escuro

​Sobrescrita Parcial do Tema

​Configuração do Tema com Outras Opções

​Tipos TypeScript

​Tratamento de Erros

​Melhores Práticas

​Solução de Problemas

​Habilitando Carteiras Digitais

​Configuração Rápida para Apple Pay

​Suporte a Navegadores

​Checkout em Sobreposição vs Inline

​Recursos Relacionados

Checkout Inline

API de Sessões de Checkout

Webhooks

Guia de Integração

Visão Geral

Demonstração

Começo Rápido

Guia de Integração Passo a Passo

Referência da API

Configuração

Opções de Inicialização

Opções de Checkout

Métodos

Abrir Checkout

Fechar Checkout

Verificar Status

Eventos

Dados do Evento de Status do Checkout

Dados do Evento de Redirecionamento do Checkout Solicitado

Opções de Implementação

Instalação via Gerenciador de Pacotes

Implementação CDN

Personalização de Tema

Configuração Básica do Tema

Configuração Completa do Tema

Somente Modo Claro

Somente Modo Escuro

Sobrescrita Parcial do Tema

Configuração do Tema com Outras Opções

Tipos TypeScript

Tratamento de Erros

Melhores Práticas

Solução de Problemas

Habilitando Carteiras Digitais

Configuração Rápida para Apple Pay

Suporte a Navegadores

Checkout em Sobreposição vs Inline

Recursos Relacionados