Pular para o conteúdo principal

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
Imagem de Capa do Checkout Embutido

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 frame de checkout embutido lida com todas as informações de pagamento sensíveis de forma segura, garantindo conformidade PCI sem certificação adicional do seu lado.

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 embutido com elementos obrigatórios rotulados

Example inline checkout layout showing required elements

  1. 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.
  2. Descrições dos itens: Uma descrição do que está sendo comprado.
  3. Totais da transação: Totais da transação, incluindo subtotal, total de impostos e total geral. Certifique-se de incluir a moeda também.
  4. 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.
  5. 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 frame completo do checkout embutido, 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.
1

Customer opens checkout

Você pode abrir o checkout embutido 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 do checkout com lista de itens e formulário de pagamento
2

Customer enters their details

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

Customer selects payment method

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.Formulário de métodos de pagamento disponíveis e detalhes do cartão
4

Checkout completed

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 check de confirmação
5

Dodo Payments creates subscription

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

Guia de Integração Passo a Passo

1

Install the SDK

Instale o SDK de Checkout da Dodo Payments:
2

Initialize the SDK for Inline Display

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

Create a Container Element

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

Open the Checkout

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

Test Your Integration

  1. Inicie seu servidor de desenvolvimento:
  1. 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 checkout.breakdown registrados no console do navegador se você adicionou um log no callback onEvent.
6

Go Live

Quando você estiver pronto para produção:
  1. Altere o modo para 'live':
  1. Atualize suas URLs de checkout para usar sessões de checkout ao vivo do seu backend.
  2. Teste o fluxo completo em produção.

Exemplo Completo em React

Este exemplo demonstra como implementar um resumo de pedido customizado junto ao checkout embutido, mantendo-os sincronizados usando o evento checkout.breakdown.

Referência da API

Configuração

Opções de Inicialização

Opções de Checkout

Métodos

Abrir Checkout

Abre o quadro de checkout no contêiner especificado.
Você também pode passar opções adicionais para personalizar o comportamento do checkout:

Fechar Checkout

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

Verificar Status

Retorna se o quadro de checkout está atualmente injetado.

Eventos

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

Dados de Detalhamento do Checkout

O evento checkout.breakdown fornece os seguintes dados:

Compreendendo o Evento de Detalhamento

O evento checkout.breakdown é a principal forma de manter a UI do seu aplicativo em sincronia com o estado do checkout do Dodo Payments. Quando ocorre:
  • Na inicialização: Imediatamente após o quadro de checkout ser carregado e pronto.
  • Na mudança de endereço: Sempre que o cliente seleciona um país ou insere um código postal que resulta em recalcular imposto.
Detalhes dos Campos: Dicas de Integração Chave:
  1. Formatação de Moeda: Os preços são sempre retornados como números inteiros na menor unidade de moeda (por exemplo, centavos para USD, ienes para JPY). Para exibi-los, divida por 100 (ou a potência de 10 apropriada) ou use uma biblioteca de formatação como Intl.NumberFormat.
  2. Tratamento de Estados Iniciais: Quando o checkout carrega pela primeira vez, tax e discount podem ser 0 ou null até que o usuário forneça suas informações de cobrança ou aplique um código. Sua UI deve lidar com esses estados graciosamente (por exemplo, mostrando um traço ou ocultando a linha).
  3. O “Total Final” vs “Total”: Enquanto total fornece o cálculo do preço padrão, finalTotal é a fonte da 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.
  4. 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 “ao vivo” à sua página de checkout e reduz o atrito 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 via CDN

Para integração rápida sem uma etapa de build, você pode usar nosso CDN:

Atualizar Método de Pagamento

O checkout embutido suporta atualizações de método de pagamento para assinaturas. Quando um cliente precisa atualizar seu método de pagamento — seja para uma assinatura ativa ou para reativar uma assinatura em espera — você pode renderizar o fluxo de atualização diretamente no layout da sua página.

Como Funciona

  1. Chame a API de Atualização de Método de Pagamento para obter um payment_link:
  1. Passe o payment_link retornado como o checkoutUrl para abrir o checkout embutido:
O quadro embutido renderiza apenas o formulário de coleta de método de pagamento. Os clientes podem inserir novos detalhes do cartão ou selecionar um método de pagamento salvo sem sair da sua página.

Para Assinaturas em Espera

Ao atualizar o método de pagamento de uma assinatura em status on_hold, o Dodo Payments cria automaticamente uma cobrança para quaisquer dívidas remanescentes. Monitore os webhooks payment.succeeded e subscription.active para confirmar a reativação.
Você também pode usar um método de pagamento salvo existente, em vez de coletar novos detalhes, passando type: 'existing' com um payment_method_id para a API de Atualização de Método de Pagamento.

Tratamento de Erros

O SDK fornece informações detalhadas sobre erros através do sistema de eventos. Sempre implemente tratamento adequado de erros em seu callback onEvent:
Sempre trate o evento checkout.error para proporcionar uma boa experiência ao usuário quando problemas ocorrerem.

Melhores Práticas

  1. Design Responsivo: Certifique-se de que seu elemento contêiner tenha largura e altura suficientes. O iframe normalmente se expande para preencher seu contêiner.
  2. Sincronização: Use o evento checkout.breakdown para manter seu resumo de pedido personalizado ou tabelas de preços em sincronia com o que o usuário vê no frame de checkout.
  3. Estados de Esqueleto: Mostre um indicador de carregamento em seu contêiner até que o evento checkout.opened seja disparado.
  4. Limpeza: Chame DodoPayments.Checkout.close() quando seu componente desmontar para limpar o iframe e os listeners de eventos.
Para implementações em modo escuro, é recomendado usar #0d0d0d como a cor de fundo para uma integração visual ótima com o frame de checkout embutido.

Validação de Status de Pagamento

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

Por Que a Validação no Lado do Servidor é Essencial

Embora os eventos de checkout embutido forneçam feedback em tempo real, eles não devem ser sua única fonte de verdade para o status de pagamento. Problemas de rede, falhas no navegador ou usuários fechando a página podem fazer com que eventos sejam perdidos. Para garantir validação de pagamento confiável:
  1. Seu servidor deve ouvir eventos de webhook - Dodo Payments envia webhooks para alterações de status de pagamento
  2. Implemente um mecanismo de polling - Sua interface deve verificar seu servidor por atualizações de status
  3. Combine ambas as abordagens - Use webhooks como fonte principal e polling como um retaguarda

Arquitetura Recomendada

Passos de Implementação

1. Ouça eventos de checkout - Quando o usuário clica em pagar, comece a preparar a verificação do status:
2. Faça polling em seu servidor - Crie um endpoint que verifica seu banco de dados para o status de pagamento (atualizado por webhooks):
3. Trate webhooks no lado do servidor - Atualize seu banco de dados quando o Dodo enviar webhooks payment.succeeded ou payment.failed. Consulte nossa documentação de Webhooks para detalhes.

Solução de Problemas

  • Verifique se elementId coincide com o id de um div que realmente existe no DOM.
  • Certifique-se de que displayType: 'inline' foi passado para Initialize.
  • Verifique se checkoutUrl é válido.
  • Certifique-se de que está ouvindo o evento checkout.breakdown.
  • Impostos são calculados apenas depois que o usuário insere um país e código postal válidos no quadro de checkout.

Ativando Carteiras Digitais

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

Configuração Rápida para Apple Pay

A verificação de domínio é necessária apenas para checkout embutido (inline). O checkout em overlay, checkout hospedado e links de pagamento não precisam disso.
O Apple Pay é verificado por domínio a partir do dashboard.
1

Open Wallet domains

Vá para Configurações → Métodos de Pagamento e, na linha de Apple Pay, clique em Gerenciar domínios.
Botão de Gerenciar Domínios na linha Apple Pay em Configurações de Métodos de Pagamento

Open Wallet domains from the Apple Pay row

2

Download the domain association file

No painel de domínios da Carteira, baixe o arquivo de associação.
Painel de domínios da Carteira com o botão Baixar arquivo

Download the Apple Pay domain association file

3

Register your domain

Clique em Registrar domínio e insira o domínio onde você incorpora o checkout embutido (por exemplo, shop.example.com), em seguida, clique em Continuar.
Formulário de Registrar um domínio com um domínio inserido

Register the domain where you embed inline checkout

4

Host the file on your domain

Hospede-o em:
Deve ser servido via HTTPS, acessível sem redirecionamentos e servido com Content-Type: application/octet-stream ou text/plain.
5

Verify the domain

Clique em Verificar domínio. A Dodo Payments confirma que o arquivo está ativo e envia seu domínio para a Apple.
Tela de Verificar seu domínio com o caminho do host do arquivo de associação e botão Verificar domínio

Verify the hosted association file

6

Confirm it's active

Quando o status mostrar Ativo, o Apple Pay está habilitado para esse domínio. Use o toggle Habilitado para ativá-lo ou desativá-lo por domínio.
Lista de domínios da Carteira mostrando domínios com status Ativo do Apple Pay e toggles Habilitados

Verified domains show an Active status

7

Test the integration

  1. Abra o checkout em um dispositivo Apple
  2. Verifique se o botão Apple Pay aparece
  3. Complete uma transação de teste

Suporte ao Navegador

O SDK de Checkout do Dodo Payments suporta os seguintes navegadores:
  • Chrome (última versão)
  • Firefox (última versão)
  • Safari (última versão)
  • Edge (última versão)
  • IE11+

Checkout Embutido vs Checkout em Overlay

Escolha o tipo de checkout certo para seu caso de uso:
Use checkout embutido quando desejar o máximo controle sobre a experiência de checkout e branding integrado. Use checkout em overlay para integração mais rápida com mudanças mínimas nas suas páginas existentes.

Recursos Relacionados

Overlay Checkout

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

Checkout Sessions API

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

Webhooks

Gerencie eventos de pagamento no servidor com webhooks.

Integration Guide

Guia completo para integrar Dodo Payments.
Para mais ajuda, visite nossa comunidade no Discord ou entre em contato com nossa equipe de suporte a desenvolvedores.
Última modificação em 9 de julho de 2026