Skip to main content

Checkout Sessions

Crie um checkout seguro e hospedado para pagamentos avulsos e assinaturas.

Payment Links

Compartilhe uma URL para receber pagamentos sem código.

Webhooks

Monitore eventos de pagamento e processe os pedidos.

API Reference

Documentação completa dos endpoints e testes ao vivo.

Pré-requisitos

Antes de começar, você precisa de:
  • Uma conta Dodo Payments.
  • Pelo menos um produto. Crie-o em Products no dashboard. Um produto de assinatura com preço diferente de zero deve custar US1oumais,ouoequivalentenamoedacorrespondente.UmaassinaturadeUS 1 ou mais, ou o equivalente na moeda correspondente. Uma assinatura de US 0 também é compatível.
  • Uma chave de API. Crie-a em Developer → API Keys e armazene-a na variável de ambiente DODO_PAYMENTS_API_KEY. Crie a chave no modo de teste enquanto estiver desenvolvendo: os exemplos desta página usam o modo de teste, e uma chave do modo de teste funciona somente com o modo de teste. Consulte Authentication.

Escolha um caminho de integração

O checkout em overlay e o checkout inline funcionam somente em uma página da web. Em um aplicativo móvel nativo, crie a sessão de checkout no seu servidor e abra o checkout_url usando um SDK de checkout móvel. Para que um agente de programação crie essa integração para você, instale o Agent Plugin.

Sessões de checkout

Crie uma experiência de checkout segura e hospedada. Você cria uma sessão no seu servidor e redireciona o cliente para o checkout_url retornado.
Cada checkout_url funciona uma vez e expira após 24 horas, ou após 15 minutos quando você passa confirm: true. Com confirm: true, você também deve fornecer todos os campos obrigatórios. Crie uma nova sessão para cada cliente e cada tentativa de pagamento.

Criar uma sessão de checkout

Redirecionar para o checkout

Depois de criar uma sessão, redirecione o cliente para o checkout_url:
Para personalizações avançadas, consulte o guia completo de Checkout Sessions e a API Reference.
Um link de pagamento é uma URL que abre o checkout para um produto, permitindo receber pagamentos sem escrever código. Os parâmetros de consulta preenchem previamente os dados do cliente e controlam o formulário de checkout. Quando um cliente abre o link, o checkout armazena os parâmetros em uma sessão e reduz a URL a um parâmetro session, para que uma atualização da página os mantenha. Um link de pagamento estático é uma URL que você cria uma vez e compartilha várias vezes. A URL base é:
Adicione parâmetros de consulta para personalizar o checkout:
integer
padrão:"1"
Número de itens a serem comprados.
string
obrigatório
Os links de pagamento usam redirect_url. A API de Checkout Sessions usa return_url para a mesma finalidade.URL para redirecionar após o pagamento. Dodo Payments adiciona os detalhes do pagamento como parâmetros de consulta, por exemplo, https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Se o produto emitir chaves de licença, um parâmetro license_key também será adicionado, com várias chaves separadas por vírgulas.
string
Especifica a moeda do pagamento. O padrão é a moeda do país de cobrança.
boolean
padrão:"true"
Mostra ou oculta o seletor de moeda.
boolean
padrão:"true"
Mostra ou oculta a seção de descontos. Defina como false para impedir que os clientes insiram códigos de cupom.
number
Fixa o valor cobrado, em unidades principais da moeda, por exemplo, 12.5 para US$ 12,50. Funciona somente com produtos Pay What You Want e é ignorado se estiver abaixo do preço mínimo do produto.
paymentAmount usa unidades principais da moeda (12.5 equivale a US12,50).Ocampo‘productcart[].amount‘daAPIdeCheckoutSessionsusaamenorunidadedamoeda(‘1250‘equivaleaUS 12,50). O campo `product_cart[].amount` da API de Checkout Sessions usa a menor unidade da moeda (`1250` equivale a US 12,50). Consulte Dynamic Pricing.
string
Campos de metadados personalizados, por exemplo, metadata_orderId=123.

Preencher previamente as informações do cliente

Adicione os campos do cliente como parâmetros de consulta para agilizar o checkout:
string
Nome completo do cliente (ignorado se firstName ou lastName for fornecido).
string
Primeiro nome do cliente.
string
Sobrenome do cliente.
string
Endereço de e-mail do cliente.
string
País do cliente (código ISO 3166-1 alpha-2).
string
Endereço.
string
Cidade.
string
Estado ou província.
string
Código postal ou ZIP Code.

Desativar campos do formulário

Para impedir que os clientes alterem informações preenchidas previamente, desative um campo fornecendo seu valor e definindo o sinalizador disable... correspondente como true:
A desativação dos campos evita alterações acidentais e garante a consistência dos dados.
Os endpoints POST /payments e POST /subscriptions estão obsoletos. Use Checkout Sessions para novas integrações.
Para integrações existentes que usam links de pagamento dinâmicos, passe payment_link: true para Create One-Time Payment ou Create Subscription para criar um link. Os exemplos abaixo criam um link de pagamento avulso. Para assinaturas, consulte o Subscription Integration Guide.

Webhooks

Os webhooks informam ao seu servidor quando um pagamento é aprovado ou falha, para que você possa processar o pedido.

Criar um endpoint de webhook

Acesse Developer → Webhooks no dashboard e adicione a URL do seu endpoint. Copie o segredo de assinatura do endpoint para a variável de ambiente DODO_PAYMENTS_WEBHOOK_KEY. Veja um exemplo usando Next.js:
app/api/webhooks/dodo/route.ts
Nossa implementação de webhook segue a especificação Standard Webhooks.

Eventos a serem monitorados

No mínimo, monitore estes eventos em um fluxo de pagamento avulso:
Sempre processe o pedido com base em payment.succeeded recebido pelo webhook, não no redirecionamento do navegador. O redirecionamento pode não ocorrer se o cliente fechar a aba, enquanto o webhook é reenviado até ser reconhecido.
Se você vende produtos com chaves de licença, também processe license_key.created. Para obter a lista completa de eventos, incluindo eventos de assinatura, entitlement, crédito, recuperação e cobrança de inadimplência, consulte o Webhook Event Guide. Para ver um exemplo completo com Next.js e TypeScript, consulte o demo repository e sua live deployment.

Moeda e endereço de cobrança

Para cobrar em uma moeda específica, passe billing_currency e billing_address.country ao criar a sessão de checkout. Se você não os informar, Adaptive Currency escolherá a moeda e o país com base no endereço IP do cliente, que pode não corresponder à moeda que você pretende cobrar. Os valores de Pay What You Want são expressos na moeda base do produto, que deve ser USD, GBP ou EUR. Para cobrar um valor fixo em outra moeda, use Adaptive Currency, que converte seu preço base usando taxas de câmbio atuais, ou Localized Pricing, que define um preço fixo por moeda. Localized Pricing não funciona com Pay What You Want.

Compra recorrente com um clique

Para cobrar um cliente recorrente usando um método de pagamento salvo, passe o payment_method_id junto com confirm: true. payment_method_id só é aceito quando confirm é true, e você também deve passar o customer_id do cliente existente. Como confirm é true, você também deve passar um billing_address completo. A sessão cobra diretamente o método de pagamento salvo, portanto não retorna um checkout_url. Use webhooks para saber se o pagamento foi aprovado.

Páginas relacionadas

Checkout Sessions

Guia completo com opções avançadas de personalização.

Overlay Checkout

Incorpore o checkout como um overlay modal na sua página.

Inline Checkout

Incorpore o checkout diretamente ao layout da sua página.

Subscription Integration

Configure a cobrança recorrente.

Webhook Event Guide

Lista completa de todos os eventos de webhook.

API Reference

Documentação da API de Checkout Sessions.
Última modificação em 26 de setembro de 2026