
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 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:
Example inline checkout layout showing required elements
- 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.
- Descrições dos itens: Uma descrição do que está sendo comprado.
- Totais da transação: Subtotal, imposto total e total geral, incluindo a moeda.
- 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.
- 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.
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.Customer opens checkout
checkout.breakdown, para exibir e atualizar informações na página.
Customer enters their details
Customer selects payment method

Checkout completed

Dodo Payments creates the payment or subscription

Início rápido
Instale o SDK, inicialize-o para o modo inline e abra o checkout em um elemento contêiner:Integração passo a passo
Install the SDK
Initialize the SDK for Inline Display
displayType: 'inline'. Escute o evento checkout.breakdown para atualizar sua interface com cálculos de impostos e totais em tempo real:Create a Container Element
Open the Checkout
DodoPayments.Checkout.open() com o checkoutUrl e o elementId do seu contêiner:Test Your Integration
- Inicie seu servidor de desenvolvimento:
- 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
checkout.breakdown registrados no console do navegador se tiver adicionado um registro no console no callback onEvent.Go Live
- Altere o modo para
'live':
- Atualize suas URLs de checkout para usar sessões de checkout de produção 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 ambos sincronizados usando o eventocheckout.breakdown:
Referência da API
Inicializar
ChameInitialize 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 callbackonEvent. Para o checkout inline, checkout.breakdown é especialmente útil para sincronizar sua interface:
Dados detalhados do checkout
O eventocheckout.breakdown fornece informações de preços e impostos:
- 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. - Gerenciamento dos estados iniciais: Quando o checkout é carregado pela primeira vez,
taxediscountpodem ser0ounullaté 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. - “Total final” versus “Total”: Embora
totalforneça o cálculo de preço padrão,finalTotalé a fonte de verdade da transação. SefinalTotalestiver presente, ele refletirá exatamente o que será cobrado no cartão do cliente. - Feedback em tempo real: Use o campo
taxpara 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
- Chame a API de atualização do método de pagamento para obter um
payment_link:
- Passe o
payment_linkretornado comocheckoutUrlpara abrir o checkout inline:
Para assinaturas suspensas
Ao atualizar o método de pagamento de uma assinatura no statuson_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.
Tratamento de erros
Sempre implemente o tratamento de erros no seu callbackonEvent:
Práticas recomendadas
- Design responsivo: Garanta que seu elemento contêiner tenha largura e altura suficientes. O iframe normalmente se expandirá para preencher o contêiner.
- Sincronização: Use o evento
checkout.breakdownpara manter seu resumo de pedido personalizado ou suas tabelas de preços sincronizados com o que o usuário vê no frame de checkout. - Estados de esqueleto: Exiba um indicador de carregamento no contêiner até que o evento
checkout.openedseja disparado. - Limpeza: Chame
DodoPayments.Checkout.close()quando seu componente for desmontado para limpar o iframe e os listeners de eventos.
#0d0d0d como cor de fundo para obter a melhor integração visual com o frame de checkout inline.Validação do status do pagamento
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:- Escute os eventos de webhook - O Dodo Payments envia webhooks para alterações no status do pagamento
- Implemente um mecanismo de polling - Seu frontend deve consultar periodicamente seu servidor em busca de atualizações de status
- 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:payment.succeeded ou payment.failed. Consulte nossa documentação de Webhooks para obter detalhes.
Solução de problemas
Checkout frame is not appearing
Checkout frame is not appearing
- Verifique se
elementIdcorresponde aoidde umdivque realmente existe no DOM - Certifique-se de que
displayType: 'inline'foi passado paraInitialize - Verifique se
checkoutUrlé válido
Taxes are not updating in my UI
Taxes are not updating in my UI
- 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
Open Wallet domains

Open Wallet domains from the Apple Pay row
Download the domain association file

Download the Apple Pay domain association file
Register your domain
shop.example.com; depois clique em Continue.
Register the domain where you embed inline checkout
Host the file on your domain
Content-Type: application/octet-stream ou text/plain.Verify the domain

Verify the hosted association file
Confirm it's active

Verified domains show an Active status
Test the integration
- Abra o checkout em um dispositivo Apple
- Verifique se o botão do Apple Pay aparece
- 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+