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 da Dodo Payments.
  • Pelo menos um produto. Crie-o em Products no dashboard. Um produto de assinatura com preço diferente de zero deve atender ao mínimo de assinatura para a moeda em que o cliente paga: $1.00 para USD. As moedas diferentes de USD, EUR e GBP também devem valer pelo menos $1.00. Uma assinatura de $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 desenvolve: os exemplos nesta página usam o modo de teste, e uma chave do modo de teste funciona apenas no modo de teste. Consulte Authentication.
  • O SDK para sua linguagem. O SDK do Node.js requer Node.js 20 ou posterior, o SDK do Python requer Python 3.9 ou posterior, e o SDK do Go requer Go 1.22 ou posterior. Os exemplos de cURL não precisam de SDK.
O exemplo de webhook também usa o pacote standardwebhooks. Instale-o com npm install standardwebhooks.

Escolha um caminho de integração

O checkout em sobreposição e o checkout incorporado funcionam apenas 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 com um SDK de checkout móvel. Para que um agente de programação crie essa integração para você, instale o Agent Plugin.

Checkout Sessions

Crie uma experiência de checkout segura e hospedada. Você cria uma sessão no seu servidor e, em seguida, 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ê fornece 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ção avançada, consulte o guia completo de Checkout Sessions e a API Reference.

Tratar erros

Quando uma solicitação falha, a API retorna um código de status HTTP e um corpo JSON com um code e um message. Baseie o tratamento de erros em code, não em message. Para consultar cada código, sua causa e como resolvê-lo, veja Error Codes. Um pagamento malsucedido é informado separadamente: o status do pagamento é failed, seu error_code informa o motivo, e você recebe um webhook payment.failed. Para decidir se deve tentar novamente, consulte Handle Payment Failures. Um link de pagamento é uma URL que abre o checkout para um produto, permitindo coletar 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 comprar.
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. A Dodo Payments acrescenta 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á acrescentado, 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, nas unidades principais da moeda, por exemplo, 12.5 para $12.50. Funciona apenas 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 corresponde a $12.50). O campo product_cart[].amount da API de Checkout Sessions usa a menor unidade da moeda (1250 corresponde a $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.

Desabilitar campos do formulário

Para impedir que os clientes alterem informações preenchidas previamente, desabilite um campo fornecendo seu valor e definindo a flag disable... correspondente como true:
A desabilitação dos campos evita alterações acidentais e garante a consistência dos dados.
Os endpoints POST /payments e POST /subscriptions estão obsoletos. Em novas integrações, use Checkout Sessions.
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 único. Para assinaturas, consulte o Subscription Integration Guide.

Webhooks

Os webhooks informam ao seu servidor quando um pagamento é bem-sucedido ou falha, permitindo que você cumpra 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 único:
Sempre cumpra o pedido com base em payment.succeeded recebido do 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, trate também license_key.created. Para consultar a lista completa de eventos, incluindo eventos de assinatura, entitlement, crédito, recuperação e cobrança de inadimplência, veja o Webhook Event Guide. Para consultar um exemplo completo com Next.js e TypeScript, veja o repositório de demonstração e sua implantação ativa.

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 fornecer, a 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 estão na moeda base do produto, que deve ser USD, GBP ou EUR. Para cobrar um valor fixo em outra moeda, use a Adaptive Currency, que converte seu preço base com base nas taxas de câmbio atuais, ou o Localized Pricing, que define um preço fixo por moeda. O Localized Pricing não funciona com Pay What You Want.

Compra recorrente com um clique

Para cobrar um cliente recorrente com um método de pagamento salvo, passe seu payment_method_id junto com confirm: true. payment_method_id é aceito apenas 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, ou apenas country e zipcode quando minimal_address é true. A sessão cobra diretamente o método de pagamento salvo, portanto não retorna nenhum checkout_url. Use webhooks para saber se o pagamento foi bem-sucedido.

Páginas relacionadas

Checkout Sessions

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

Overlay Checkout

Incorpore o checkout como uma sobreposição 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 8 de outubro de 2026