Checkout Inline - Dodo Payments Documentation

Visão Geral

O checkout inline permite que você crie experiências de checkout totalmente integradas que se misturam perfeitamente com seu site ou aplicativo. Ao contrário do checkout em sobreposição, que se abre como um modal sobre sua página, o checkout inline incorpora o formulário de pagamento diretamente no layout da sua página. Usando o checkout inline, você pode:

Criar experiências de checkout que estão totalmente integradas ao seu aplicativo ou site
Permitir que o Dodo Payments capture com segurança as informações do cliente e de pagamento em um quadro de checkout otimizado
Exibir itens, totais e outras informações do Dodo Payments em sua página
Usar métodos e eventos da SDK para construir experiências de checkout avançadas

Como Funciona

O checkout inline funciona incorporando um quadro seguro do Dodo Payments em seu site ou aplicativo. O quadro de checkout lida com a coleta de informações do cliente e a captura de detalhes de pagamento. Sua página exibe a lista de itens, totais e opções para alterar o que está no checkout. A SDK permite que sua página e o quadro de checkout interajam entre si. O Dodo Payments cria automaticamente uma assinatura quando um checkout é concluído, pronto para você provisionar.

O quadro de checkout inline lida com segurança todas as informações sensíveis de pagamento, garantindo conformidade com PCI sem certificação adicional da sua parte.

O Que Faz um Bom Checkout Inline?

É importante que os clientes saibam de quem estão comprando, o que estão comprando e quanto estão pagando. Para construir um checkout inline que seja compatível e otimizado para conversão, sua implementação deve incluir:

Exemplo de checkout inline com elementos obrigatórios rotulados

Informações recorrentes: Se for recorrente, com que frequência ocorre e o total a ser pago na renovação. Se for um teste, quanto tempo dura o teste.
Descrições dos itens: Uma descrição do que está sendo comprado.
Totais da transação: Totais da transação, incluindo subtotal, total de impostos e total geral. Certifique-se de incluir a moeda também.
Rodapé do Dodo Payments: O quadro completo do checkout inline, incluindo o rodapé do checkout que contém informações sobre o Dodo Payments, nossos termos de venda e nossa política de privacidade.
Política de reembolso: Um link para sua política de reembolso, se for diferente da política padrão de reembolso do Dodo Payments.

Sempre exiba o quadro completo do checkout inline, incluindo o rodapé. Remover ou ocultar informações legais viola os requisitos de conformidade.

Jornada do Cliente

O fluxo de checkout é determinado pela configuração da sua sessão de checkout. Dependendo de como você configura a sessão de checkout, os clientes experimentarão um checkout que pode apresentar todas as informações em uma única página ou em várias etapas.

Cliente abre o checkout

Você pode abrir o checkout inline passando itens ou uma transação existente. Use o SDK para mostrar e atualizar informações na página, e métodos do SDK para atualizar itens com base na interação do cliente.

Página inicial de checkout com lista de itens e formulário de pagamento

Cliente insere seus dados

O checkout inline primeiro pede aos clientes que insiram seu endereço de e-mail, selecionem seu país e (quando necessário) insiram seu CEP ou código postal. Esta etapa coleta todas as informações necessárias para determinar impostos e opções de pagamento disponíveis.Você pode preencher automaticamente os detalhes do cliente e apresentar endereços salvos para agilizar a experiência.

Cliente seleciona o método de pagamento

Após inserir seus dados, os clientes são apresentados com os métodos de pagamento disponíveis e o formulário de pagamento. As opções podem incluir cartão de crédito ou débito, PayPal, Apple Pay, Google Pay e outros métodos de pagamento locais com base em sua localização.Exiba métodos de pagamento salvos, se disponíveis, para acelerar o checkout.

Métodos de pagamento disponíveis e formulário de detalhes do cartão

Checkout concluído

O Dodo Payments direciona cada pagamento para o melhor adquirente para aquela venda, garantindo a melhor chance possível de sucesso. Os clientes entram em um fluxo de sucesso que você pode construir.

Tela de sucesso com marca de confirmação

Dodo Payments cria assinatura

O Dodo Payments cria automaticamente uma assinatura para o cliente, pronta para você provisionar. O método de pagamento que o cliente usou é mantido em arquivo para renovações ou alterações de assinatura.

Assinatura criada com notificação de webhook

Começo Rápido

Comece com o Checkout Inline da Dodo Payments em apenas algumas linhas de código:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});

Certifique-se de ter um elemento de contêiner com o correspondente id na sua página: <div id="dodo-inline-checkout"></div>.

Guia de Integração Passo a Passo

Instalar o SDK

Instale o SDK de Checkout da Dodo Payments:

npm install dodopayments-checkout

Inicializar o SDK para Exibição Inline

Inicialize o SDK e especifique displayType: 'inline'. Você também deve escutar o evento checkout.breakdown para atualizar sua interface com cálculos de impostos e totais em tempo real.

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});

Criar um Elemento Contêiner

Adicione um elemento ao seu HTML onde o quadro de checkout será injetado:

<div id="dodo-inline-checkout"></div>

Abrir o Checkout

Chame DodoPayments.Checkout.open() com o checkoutUrl e o elementId do seu contêiner:

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

Teste Sua Integração

Inicie seu servidor de desenvolvimento:

npm run dev

Teste o fluxo de checkout:
- Insira seu e-mail e detalhes de endereço no quadro inline.
- Verifique se seu resumo de pedido personalizado é atualizado em tempo real.
- Teste o fluxo de pagamento usando credenciais de teste.
- Confirme se os redirecionamentos funcionam corretamente.

Você deve ver eventos de checkout.breakdown registrados no console do seu navegador se você adicionou um log de console no callback de onEvent.

Ir para Produção

Quando você estiver pronto para produção:

Altere o modo para 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

Atualize suas URLs de checkout para usar sessões de checkout ao vivo do seu backend.
Teste o fluxo completo em produção.

Exemplo Completo em React

Este exemplo demonstra como implementar um resumo de pedido personalizado ao lado do checkout inline, mantendo-os sincronizados usando o evento checkout.breakdown.

"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

Referência da API

Configuração

Opções de Inicialização

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}

Opção	Tipo	Requerido	Descrição
`mode`	`"test" \| "live"`	Sim	Modo de ambiente.
`displayType`	`"inline" \| "overlay"`	Sim	Deve ser definido como `"inline"` para embutir o checkout.
`onEvent`	`function`	Sim	Função de callback para manipular eventos de checkout.

Opções de Checkout

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

Opção	Tipo	Requerido	Descrição
`checkoutUrl`	`string`	Sim	URL da sessão de checkout.
`elementId`	`string`	Sim	O `id` do elemento DOM onde o checkout deve ser renderizado.
`options.showTimer`	`boolean`	Não	Mostrar ou ocultar o temporizador do 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 selo 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á eventos de `checkout.status` e `checkout.redirect_requested` para gerenciar o redirecionamento você mesmo.
`options.themeConfig`	`ThemeConfig`	Não	Configuração de tema personalizada.
`options.payButtonText`	`string`	Não	Texto personalizado a ser exibido no botão de pagamento.
`options.fontSize`	`FontSize`	Não	Tamanho de fonte global para o checkout.
`options.fontWeight`	`FontWeight`	Não	Peso de fonte global para o checkout.

Métodos

Abrir Checkout

Abre o quadro de checkout no contêiner especificado.

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

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});

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

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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

Remove programaticamente o quadro de checkout e limpa os ouvintes de eventos.

DodoPayments.Checkout.close();

Verificar Status

Retorna se o quadro de checkout está atualmente injetado.

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

Eventos

O SDK fornece eventos em tempo real através do callback de onEvent. Para o checkout inline, checkout.breakdown é particularmente útil para sincronizar sua interface.

Tipo de Evento	Descrição
`checkout.opened`	O quadro de checkout foi carregado.
`checkout.breakdown`	Disparado quando preços, impostos ou descontos são atualizados.
`checkout.customer_details_submitted`	Os detalhes do cliente foram enviados.
`checkout.pay_button_clicked`	Disparado quando o cliente clica no botão de pagamento. Útil para análises e rastreamento de funis de conversão.
`checkout.redirect`	O checkout realizará um redirecionamento (por exemplo, para uma página bancária).
`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.

Dados de Quebra do Checkout

O evento checkout.breakdown fornece os seguintes dados:

interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

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

Entendendo o Evento de Quebra

O evento checkout.breakdown é a principal maneira de manter a interface da sua aplicação sincronizada com o estado do checkout do Dodo Payments. Quando ele é disparado:

Na inicialização: Imediatamente após o quadro de checkout ser carregado e estar pronto.
Na mudança de endereço: Sempre que o cliente seleciona um país ou insere um código postal que resulta em um recálculo de impostos.

Detalhes do Campo:

Campo	Descrição
`subTotal`	A soma de todos os itens da sessão antes que quaisquer descontos ou impostos sejam aplicados.
`discount`	O valor total de todos os descontos aplicados.
`tax`	O valor do imposto calculado. No modo `inline`, isso é atualizado dinamicamente à medida que o usuário interage com os campos de endereço.
`total`	O resultado matemático de `subTotal - discount + tax` na moeda base da sessão.
`currency`	O código da moeda ISO (por exemplo, `"USD"`) para os valores padrão de subtotal, desconto e imposto.
`finalTotal`	O valor real que o cliente é cobrado. Isso pode incluir ajustes adicionais de câmbio ou taxas de métodos de pagamento locais que não fazem parte da divisão de preços básica.
`finalTotalCurrency`	A moeda na qual o cliente está realmente pagando. Isso pode diferir de `currency` se a paridade do poder de compra ou a conversão de moeda local estiver ativa.

Dicas de Integração Importantes:

Formatação de Moeda: Os preços são sempre retornados como inteiros na menor unidade monetária (por exemplo, centavos para USD, ienes para JPY). Para exibi-los, divida por 100 (ou a potência apropriada de 10) ou use uma biblioteca de formatação como Intl.NumberFormat.
Manipulação de Estados Iniciais: Quando o checkout é carregado pela primeira vez, tax e discount podem estar 0 ou null até que o usuário forneça suas informações de cobrança ou aplique um código. Sua interface deve lidar com esses estados de forma adequada (por exemplo, mostrando um traço — ou ocultando a linha).
O “Total Final” vs “Total”: Enquanto total fornece o cálculo de preço padrão, finalTotal é a fonte de verdade para a transação. Se finalTotal estiver presente, ele reflete exatamente o que será cobrado no cartão do cliente, incluindo quaisquer ajustes dinâmicos.
Feedback em Tempo Real: Use o campo tax para mostrar aos usuários que os impostos estão sendo calculados em tempo real. Isso proporciona uma sensação de “ao vivo” na sua página de checkout e reduz a fricção durante a etapa de entrada de endereço.

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 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 Inline 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",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </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
        inputFocusBorder: "#D0D5DD", // Input focus 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",
        inputFocusBorder: "#323232",
        
        // 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 apenas personalizar 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 apenas personalizar 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",
    },
  },
});

Sobrescrição 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 no seu callback de onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});

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

Melhores Práticas

Design Responsivo: Certifique-se de que seu elemento de contêiner tenha largura e altura suficientes. O iframe geralmente se expandirá para preencher seu contêiner.
Sincronização: Use o evento checkout.breakdown para manter seu resumo de pedido personalizado ou tabelas de preços sincronizados com o que o usuário vê no quadro de checkout.
Estados de Esqueleto: Mostre um indicador de carregamento em seu contêiner até que o evento checkout.opened seja disparado.
Limpeza: Chame DodoPayments.Checkout.close() quando seu componente for desmontado para limpar o iframe e os ouvintes de eventos.

Para implementações em modo escuro, é recomendável usar #0d0d0d como a cor de fundo para uma melhor integração visual com o quadro de checkout inline.

Validação do Status do Pagamento

Não confie apenas nos eventos de checkout inline para determinar o sucesso ou falha do pagamento. Sempre implemente validação do lado do servidor usando webhooks e/ou polling.

Por que a Validação do Lado do Servidor é Essencial

Embora eventos de checkout inline como checkout.status forneçam feedback em tempo real, eles não devem ser sua única fonte de verdade para o status do pagamento. Problemas de rede, falhas no navegador ou usuários fechando a página podem fazer com que eventos sejam perdidos. Para garantir uma validação de pagamento confiável:

Seu servidor deve escutar eventos de webhook - Dodo Payments envia webhooks para alterações no status do pagamento
Implemente um mecanismo de polling - Seu frontend deve fazer polling no seu servidor para atualizações de status
Combine ambas as abordagens - Use webhooks como a fonte primária e polling como uma alternativa

Arquitetura Recomendada

Etapas de Implementação

1. Escute eventos de checkout - Quando o usuário clicar em pagar, comece a se preparar para verificar o status:

onEvent: (event) => {
  if (event.event_type === 'checkout.status') {
    // Start polling your server for confirmed status
    startPolling();
  }
}

2. Faça polling no seu servidor - Crie um endpoint que verifica seu banco de dados para o status do pagamento (atualizado por webhooks):

// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);

3. Manipule webhooks do lado do servidor - Atualize seu banco de dados quando o Dodo enviar webhooks de payment.succeeded ou payment.failed. Veja nossa documentação sobre Webhooks para detalhes.

Manipulando Redirecionamentos (3DS, Google Pay, UPI)

Ao usar manualRedirect: true, certos métodos de pagamento exigem redirecionar o usuário para fora da sua página para autenticação:

3D Secure (3DS) - Autenticação de cartão
Google Pay - Autenticação de carteira em alguns fluxos
UPI - Redirecionamentos de método de pagamento indiano

Quando um redirecionamento é necessário, você receberá o evento checkout.redirect_requested. Redirecione o usuário para a URL fornecida:

if (event.event_type === 'checkout.redirect_requested') {
  const redirectUrl = event.data?.message?.redirect_to;
  // Save payment ID before redirect, then redirect
  sessionStorage.setItem('pendingPaymentId', paymentId);
  window.location.href = redirectUrl;
}

Após a autenticação ser concluída (sucesso ou falha), o usuário retorna à sua página. Não assuma sucesso apenas porque o usuário retornou. Em vez disso:

Verifique se o usuário está retornando de um redirecionamento (por exemplo, via sessionStorage)
Comece a fazer polling no seu servidor para o status de pagamento confirmado
Mostre um estado de “Verificando pagamento…” enquanto faz polling
Exiba a interface de sucesso/falha com base no status confirmado pelo servidor

Sempre verifique o status do pagamento do lado do servidor após redirecionamentos. O retorno do usuário à sua página significa apenas que a autenticação foi concluída—não indica se o pagamento foi bem-sucedido ou falhou.

Solução de Problemas

O quadro de checkout não está aparecendo

Verifique se elementId corresponde ao id de um div que realmente existe no DOM.
Certifique-se de que displayType: 'inline' foi passado para Initialize.
Verifique se o checkoutUrl é válido.

Os impostos não estão atualizando na minha interface

Certifique-se de que você está escutando o evento checkout.breakdown.
Os impostos só são calculados após o usuário inserir um país e código postal válidos no quadro de checkout.

Habilitando Carteiras Digitais

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

Configuração Rápida para Apple Pay

Baixar 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 na finalização da compra e teste todo o fluxo.

O Apple Pay requer verificação de domínio antes de aparecer em produção. Entre em contato com o suporte antes de entrar em operação 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 Inline vs Overlay

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

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

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

Recursos Relacionados

Checkout Overlay

Use o checkout overlay para uma integração modal rápida.

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 para desenvolvedores.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Visão Geral

​Como Funciona

​O Que Faz um Bom Checkout Inline?

​Jornada do Cliente

​Começo Rápido

​Guia de Integração Passo a Passo

​Exemplo Completo em React

​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 de Quebra do Checkout

​Dados do Evento de Status do Checkout

​Dados do Evento de Redirecionamento do Checkout Solicitado

​Entendendo o Evento de Quebra

​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

​Sobrescrição Parcial do Tema

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

​Tipos TypeScript

​Tratamento de Erros

​Melhores Práticas

​Validação do Status do Pagamento

​Por que a Validação do Lado do Servidor é Essencial

​Arquitetura Recomendada

​Etapas de Implementação

​Manipulando Redirecionamentos (3DS, Google Pay, UPI)

​Solução de Problemas

​Habilitando Carteiras Digitais

​Configuração Rápida para Apple Pay

​Suporte a Navegadores

​Checkout Inline vs Overlay

​Recursos Relacionados

Checkout Overlay

API de Sessões de Checkout

Webhooks

Guia de Integração

Visão Geral

Como Funciona

O Que Faz um Bom Checkout Inline?

Jornada do Cliente

Começo Rápido

Guia de Integração Passo a Passo

Exemplo Completo em React

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 de Quebra do Checkout

Dados do Evento de Status do Checkout

Dados do Evento de Redirecionamento do Checkout Solicitado

Entendendo o Evento de Quebra

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

Sobrescrição Parcial do Tema

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

Tipos TypeScript

Tratamento de Erros

Melhores Práticas

Validação do Status do Pagamento

Por que a Validação do Lado do Servidor é Essencial

Arquitetura Recomendada

Etapas de Implementação

Manipulando Redirecionamentos (3DS, Google Pay, UPI)

Solução de Problemas

Habilitando Carteiras Digitais

Configuração Rápida para Apple Pay

Suporte a Navegadores

Checkout Inline vs Overlay

Recursos Relacionados