Skip to main content
O checkout inline incorpora um formulário de pagamento seguro diretamente ao layout da sua página. Diferentemente do checkout sobreposto, que é aberto como um modal, o checkout inline se torna parte da sua página. Você controla o layout e pode exibir seu próprio resumo do pedido ao lado do formulário de checkout.
Formulário de checkout inline incorporado a uma página de produto com resumo do pedido

Como funciona

O checkout inline renderiza um frame seguro do Dodo Payments em um contêiner da sua página. O frame gerencia a coleta das informações do cliente e dos dados de pagamento. Sua página exibe itens, totais e outras informações. O SDK permite que sua página e o frame de checkout se comuniquem. Quando o checkout é concluído, o Dodo Payments cria o pagamento ou a assinatura para um produto de assinatura e envia um webhook para que você possa provisionar o acesso.
O frame de checkout inline gerencia com segurança todas as informações confidenciais de pagamento, garantindo a conformidade com o PCI sem exigir certificação adicional da sua parte.

O que caracteriza um bom checkout inline

Os clientes precisam saber de quem estão comprando, o que estão comprando e quanto estão pagando. Sua implementação deve incluir:
Exemplo de checkout inline com os elementos obrigatórios identificados

Example inline checkout layout showing required elements

  1. Informações recorrentes: Se for recorrente, informe a frequência da recorrência e o total a pagar na renovação. Se houver um período de teste, informe sua duração.
  2. Descrições dos itens: Uma descrição do que está sendo comprado.
  3. Totais da transação: Subtotal, imposto total e total geral, incluindo a moeda.
  4. Rodapé do Dodo Payments: O frame de checkout inline completo, incluindo o rodapé com as informações do Dodo Payments, os termos de venda e a política de privacidade.
  5. Política de reembolso: Um link para sua política de reembolso, caso ela seja diferente da política de reembolso padrão do Dodo Payments.
Sempre exiba o frame de checkout inline completo, incluindo o rodapé. Remover ou ocultar informações legais viola os requisitos de conformidade.

Jornada do cliente

O fluxo de checkout depende da configuração da sua sessão de checkout. Dependendo de como você configura a sessão, os clientes podem ver todas as informações em uma única página ou distribuídas em várias etapas.
1

Customer opens checkout

Você abre o checkout inline passando uma URL de checkout. Use eventos do SDK, como checkout.breakdown, para exibir e atualizar informações na página.Página inicial do checkout com lista de itens e formulário de pagamento
2

Customer enters their details

Primeiro, o checkout inline solicita que os clientes insiram seu endereço de e-mail, selecionem seu país e, quando necessário, insiram seu ZIP code ou código postal. Essa etapa coleta todas as informações necessárias para determinar os impostos e as opções de pagamento disponíveis.Você pode preencher previamente os dados do cliente e apresentar endereços salvos para simplificar a experiência.
3

Customer selects payment method

Depois de inserir seus dados, os clientes veem 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 na localização do cliente.Exiba métodos de pagamento salvos, quando disponíveis, para acelerar o checkout.Métodos de pagamento disponíveis e formulário de dados do cartão
4

Checkout completed

O Dodo Payments encaminha cada pagamento ao melhor adquirente para aquela venda, buscando a maior probabilidade possível de sucesso. Os clientes entram em um fluxo de sucesso que você pode criar.Tela de sucesso com marca de confirmação
5

Dodo Payments creates the payment or subscription

O Dodo Payments cria o pagamento ou a assinatura para um produto de assinatura e envia um webhook para que você possa provisionar o acesso. O método de pagamento usado pelo cliente fica armazenado para renovações ou alterações na assinatura.Assinatura criada com notificação de webhook

Início rápido

Instale o SDK, inicialize-o para o modo inline e abra o checkout em um elemento contêiner:
Certifique-se de ter um elemento contêiner com o id correspondente na sua página: <div id="dodo-inline-checkout"></div>.

Integração passo a passo

1

Install the SDK

Instale usando npm, yarn ou pnpm:
2

Initialize the SDK for Inline Display

Inicialize o SDK e especifique displayType: 'inline'. Escute o evento checkout.breakdown para atualizar sua interface com cálculos de impostos e totais em tempo real:
3

Create a Container Element

Adicione um elemento ao seu HTML onde o frame 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 os dados do endereço no frame inline
    • Verifique se o resumo de pedido personalizado é atualizado em tempo real
    • Teste o fluxo de pagamento usando credenciais de teste
    • Confirme se os redirecionamentos funcionam corretamente
Você deverá ver eventos checkout.breakdown registrados no console do navegador se tiver adicionado um registro no console no callback onEvent.
6

Go Live

Quando estiver pronto para produção:
  1. Altere o modo para 'live':
  1. Atualize suas URLs de checkout para usar sessões de checkout de produção do seu backend
  2. 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 ambos sincronizados usando o evento checkout.breakdown:

Referência da API

Inicializar

Chame Initialize uma vez para configurar o SDK:

Abrir checkout

Abra o frame de checkout em um contêiner:

Fechar checkout

Remova o frame de checkout programaticamente e limpe os listeners de eventos:

Verificar status

Verifique se o frame de checkout está atualmente injetado:

Eventos

O SDK fornece eventos em tempo real por meio do callback onEvent. Para o checkout inline, checkout.breakdown é especialmente útil para sincronizar sua interface:

Dados detalhados do checkout

O evento checkout.breakdown fornece informações de preços e impostos:
O evento é disparado quando o frame de checkout é carregado e novamente sempre que o preço é recalculado, por exemplo, quando o cliente seleciona um país ou insere um código postal que altera o imposto. Detalhes dos campos: Dicas de integração:
  1. Formatação de moeda: Os preços são inteiros na menor unidade da moeda, por exemplo, centavos para USD. Para moedas com duas casas decimais, divida por 100 antes de formatar com Intl.NumberFormat. Moedas sem casas decimais, como JPY, não têm uma unidade menor, portanto não as divida.
  2. Gerenciamento dos estados iniciais: Quando o checkout é carregado 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. Gerencie esses estados de forma adequada, por exemplo, exibindo um traço — ou ocultando a linha.
  3. “Total final” versus “Total”: Embora total forneça o cálculo de preço padrão, finalTotal é a fonte de verdade da transação. Se finalTotal estiver presente, ele refletirá exatamente o que será cobrado no cartão do cliente.
  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 dá uma sensação de atualização à sua página de checkout e reduz o atrito durante a inserção do endereço.

Implementação via CDN

Para uma integração rápida sem uma etapa de build, carregue o SDK pela CDN:

Atualizar método de pagamento

O checkout inline oferece suporte a atualizações do método de pagamento para assinaturas. Quando um cliente precisa atualizar seu método de pagamento para uma assinatura ativa ou reativar uma assinatura suspensa, você pode renderizar o fluxo de atualização diretamente no layout da sua página.

Como funciona

  1. Chame a API de atualização do método de pagamento para obter um payment_link:
  1. Passe o payment_link retornado como checkoutUrl para abrir o checkout inline:
O frame inline renderiza somente o formulário de coleta do método de pagamento. Os clientes podem inserir novos dados do cartão ou selecionar um método de pagamento salvo sem sair da sua página.

Para assinaturas suspensas

Ao atualizar o método de pagamento de uma assinatura no status on_hold, o Dodo Payments cria automaticamente uma cobrança para quaisquer valores pendentes. 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 dados, passando type: 'existing' com um payment_method_id para a API de atualização do método de pagamento.

Tratamento de erros

Sempre implemente o tratamento de erros no seu callback onEvent:
Sempre gerencie o evento checkout.error para proporcionar uma boa experiência ao usuário quando ocorrerem erros.

Práticas recomendadas

  1. Design responsivo: Garanta que seu elemento contêiner tenha largura e altura suficientes. O iframe normalmente se expandirá para preencher o contêiner.
  2. Sincronização: Use o evento checkout.breakdown para manter seu resumo de pedido personalizado ou suas tabelas de preços sincronizados com o que o usuário vê no frame de checkout.
  3. Estados de esqueleto: Exiba um indicador de carregamento no contêiner até que o evento checkout.opened seja disparado.
  4. Limpeza: Chame DodoPayments.Checkout.close() quando seu componente for desmontado para limpar o iframe e os listeners de eventos.
Para implementações em modo escuro, use #0d0d0d como cor de fundo para obter a melhor integração visual com o frame de checkout inline.

Validação do status do pagamento

Não dependa somente dos eventos do checkout inline para determinar o sucesso ou a falha do pagamento. Sempre implemente a validação no servidor usando webhooks e/ou polling.

Por que a validação no servidor é essencial

Embora os eventos do checkout inline 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 do navegador ou usuários fechando a página podem fazer com que eventos sejam perdidos. Para garantir uma validação confiável do pagamento:
  1. Escute os eventos de webhook - O Dodo Payments envia webhooks para alterações no status do pagamento
  2. Implemente um mecanismo de polling - Seu frontend deve consultar periodicamente seu servidor em busca de atualizações de status
  3. Combine as duas abordagens - Use webhooks como fonte principal e polling como alternativa

Arquitetura recomendada

Etapas de implementação

1. Escute os eventos do checkout - Quando o usuário clicar em pagar, comece a preparar a verificação do status:
2. Consulte seu servidor - Crie um endpoint que verifique no banco de dados o status do pagamento, atualizado pelos webhooks:
3. Gerencie webhooks no servidor - Atualize seu banco de dados quando o Dodo enviar webhooks payment.succeeded ou payment.failed. Consulte nossa documentação de Webhooks para obter detalhes.

Solução de problemas

  • 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 checkoutUrl é válido
  • Certifique-se de estar escutando o evento checkout.breakdown
  • Os impostos só são calculados depois que o usuário insere um país e um código postal válidos no frame de checkout

Carteiras digitais

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

Configuração rápida do Apple Pay

A verificação de domínio é necessária somente para o checkout inline (incorporado). Ela não é necessária para o checkout hospedado.
O Apple Pay não está disponível para o checkout sobreposto.
O Apple Pay é verificado por domínio no dashboard.
1

Open Wallet domains

Acesse Settings → Payment Methods e, na linha Apple Pay, clique em Manage domains.
Botão Manage domains na linha Apple Pay nas configurações de Payment Methods

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 Download file

Download the Apple Pay domain association file

3

Register your domain

Clique em Register domain e insira o domínio onde você incorpora o checkout inline, por exemplo, shop.example.com; depois clique em Continue.
Formulário de registro de 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:
Ele deve ser servido por HTTPS, estar acessível sem redirecionamentos e ser servido com Content-Type: application/octet-stream ou text/plain.
5

Verify the domain

Clique em Verify domain. O Dodo Payments confirma que o arquivo está disponível e envia seu domínio à Apple.
Tela de verificação do domínio com o caminho do arquivo de associação hospedado e o botão Verify domain

Verify the hosted association file

6

Confirm it's active

Quando o status mostrar Active, o Apple Pay estará habilitado para esse domínio. Use o botão de alternância Enabled para ativá-lo ou desativá-lo por domínio.
Lista de domínios da carteira mostrando domínios com status Active do Apple Pay e botões de alternância Enabled

Verified domains show an Active status

7

Test the integration

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

Suporte a navegadores

O Checkout SDK do Dodo Payments oferece suporte a:
  • Chrome (versão mais recente)
  • Firefox (versão mais recente)
  • Safari (versão mais recente)
  • Edge (versão mais recente)
  • IE11+

Checkout inline versus sobreposto

Escolha o tipo de checkout adequado ao seu caso de uso:
Use o checkout inline quando quiser máximo controle sobre a experiência de checkout e branding consistente. Use o checkout sobreposto para uma integração mais rápida com alterações mínimas nas páginas existentes.

Recursos relacionados

Overlay Checkout

Use o checkout sobreposto para uma 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 o Dodo Payments.
Para obter mais ajuda, visite nossa comunidade no Discord ou entre em contato com nossa equipe de suporte a desenvolvedores.
Última modificação em 26 de setembro de 2026