Skip to main content

Prerequisites

To integrate the Dodo Payments API, you’ll need:
  • A Dodo Payments merchant account
  • API Credentials (API key and webhook secret key) from dashboard

Dashboard Setup

  1. Navigate to the Dodo Payments Dashboard
  2. Crie um produto (pagamento único ou assinatura). Os produtos de assinatura devem ter preço de pelo menos $1 (ou o equivalente na moeda escolhida); valores abaixo desse mínimo não são compatíveis.
  3. Generate your API key:
    • Go to Developer > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  4. Configure webhooks:
    • Go to Developer > Webhooks
    • Create a webhook URL for payment notifications
    • Copy the webhook secret key in env

Integration

Escolha o caminho de integração mais adequado ao seu caso de uso:
  • Checkout Sessions (recomendado): ideal para a maioria das integrações. Crie uma sessão no seu servidor e redirecione os clientes para um checkout seguro e hospedado.
  • Overlay Checkout: use quando precisar de uma experiência na página que abra o checkout como uma sobreposição modal no seu site.
  • Inline Checkout: incorpore o checkout diretamente ao layout da sua página para obter experiências de checkout totalmente integradas e personalizadas com a sua marca.
  • Static Payment Links: URLs sem código, compartilháveis instantaneamente, para coletar pagamentos rapidamente.
  • Dynamic Payment Links: links criados programaticamente. No entanto, Checkout Sessions são recomendadas e oferecem mais flexibilidade.
  • Mobile Checkout SDKs: para aplicativos nativos Android, iOS, React Native e Flutter. Crie a sessão no seu servidor conforme descrito acima e, em seguida, passe checkout_url ao SDK.
Overlay e Inline Checkout funcionam apenas no navegador — eles incorporam o checkout a uma página web. Se você estiver desenvolvendo um aplicativo móvel nativo, crie a sessão de checkout no seu servidor e abra-a usando os Mobile Checkout SDKs.

1. Checkout Sessions

Use Checkout Sessions para criar uma experiência de checkout segura e hospedada para pagamentos únicos ou assinaturas. Você cria uma sessão no seu servidor e, em seguida, redireciona o cliente para checkout_url.
As sessões de checkout são válidas por 24 horas por padrão. Se você passar confirm=true, as sessões serão válidas por 15 minutos e todos os campos obrigatórios deverão ser fornecidos.
1

Create a checkout session

Escolha o SDK de sua preferência ou chame a REST API.
2

Redirect customer to checkout

Após criar a sessão, redirecione para checkout_url para iniciar o fluxo hospedado.
Prefira Checkout Sessions para começar a aceitar pagamentos da maneira mais rápida e confiável. Para personalizações avançadas, consulte o guia de Checkout Sessions completo e a API Reference.

2. Overlay Checkout

Para uma experiência de checkout integrada à página, conheça nossa integração de Overlay Checkout, que permite aos clientes concluir pagamentos sem sair do seu site.

3. Inline Checkout

Para experiências de checkout totalmente integradas e incorporadas diretamente à sua página, use nossa integração de Inline Checkout. Ela permite criar resumos de pedidos personalizados e ter controle total sobre o layout do checkout, enquanto Dodo Payments gerencia a coleta do pagamento com segurança. Static payment links permitem aceitar pagamentos rapidamente compartilhando uma URL simples. Você pode personalizar a experiência de checkout passando query parameters para preencher previamente os dados do cliente, controlar os campos do formulário e adicionar metadados personalizados.
1

Construct your payment link

Comece com a URL base e adicione o ID do produto:
2

Add core parameters

Inclua os query parameters essenciais:
  • integer
    padrão:"1"
    Número de itens a comprar.
  • string
    obrigatório
    URL para redirecionar após a conclusão do pagamento.
A URL de redirecionamento incluirá os detalhes do pagamento como query parameters, por exemplo:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

Se o produto tiver chaves de licença habilitadas, um parâmetro license_key também será acrescentado (separado por vírgulas para várias chaves):
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
3

Pre-fill customer information (optional)

Adicione campos do cliente ou de cobrança como query parameters para agilizar o checkout.
  • string
    Nome completo do cliente (ignorado se firstName ou lastName for fornecido).
  • string
    Nome do cliente.
  • string
    Sobrenome do cliente.
  • string
    Endereço de e-mail do cliente.
  • string
    País do cliente.
  • string
    Endereço.
  • string
    Cidade.
  • string
    Estado ou província.
  • string
    Código postal/ZIP.
  • boolean
    true ou false
4

Control form fields (optional)

Você pode desabilitar campos específicos para torná-los somente leitura para o cliente. Isso é útil quando você já tem os dados do cliente (por exemplo, usuários autenticados).
Para desabilitar um campo, forneça seu valor e defina a flag disable… correspondente como true:
Desabilitar campos ajuda a evitar alterações acidentais e garante a consistência dos dados.
Definir showDiscounts=false desabilitará e ocultará a seção de descontos no formulário de checkout. Use isso se quiser impedir que os clientes insiram códigos de cupom ou promocionais durante o checkout.
5

Add advanced controls (optional)

  • 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 moedas.
  • number
    Define o valor cobrado, em unidades principais da moeda (por exemplo, 12.5 para US$ 12,50). Disponível apenas para produtos Pay What You Want. O valor é ignorado se estiver abaixo do preço mínimo do produto.
  • string
    Campos de metadados personalizados (por exemplo, metadata_orderId=123).
paymentAmount em um link de pagamento não é a mesma unidade que o campo amount na API Checkout Sessions. O parâmetro do link usa unidades principais da moeda (12.5 = US12,50),enquantoproductcart[].amountdaAPIusaamenordenominac\ca~o(1250=US 12,50), enquanto `product_cart[].amount` da API usa a menor denominação (`1250` = US 12,50). Consulte Dynamic Pricing para ver o campo da API.
6

Share the link

Envie o link de pagamento concluído ao seu cliente. Quando ele acessar o link, todos os parâmetros de consulta serão coletados e armazenados com um ID de sessão. A URL será então simplificada para incluir apenas o parâmetro de sessão (por exemplo, ?session=sess_1a2b3c4d). As informações armazenadas persistem após atualizações da página e ficam acessíveis durante todo o processo de checkout.
A experiência de checkout do cliente agora é simplificada e personalizada com base nos seus parâmetros.
Prefira Checkout Sessions para a maioria dos casos de uso, pois oferecem mais flexibilidade e controle.
Criado por meio de uma chamada de API ou do nosso SDK com os dados do cliente. Veja um exemplo: Há duas APIs para criar links de pagamento dinâmicos:
Ambos os endpoints de criação de links estão obsoletos. POST /payments e POST /subscriptions continuam funcionando para integrações existentes, mas novas integrações devem usar Checkout Sessions (POST /checkouts).
O guia abaixo mostra como criar um link de pagamento avulso. Para obter instruções detalhadas sobre a integração de assinaturas, consulte este Guia de integração de assinaturas.
Certifique-se de passar payment_link = true para obter o link de pagamento
Depois de criar o link de pagamento, redirecione seus clientes para concluir o pagamento.

Implementando Webhooks

Configure um endpoint de API para receber notificações de pagamento. Veja um exemplo usando Next.js:
Nossa implementação de webhook segue a especificação Standard Webhooks. Para ver as definições dos tipos de webhook, consulte nosso Guia de eventos de webhook.

Eventos a serem monitorados

Ative payload.type e processe os eventos relevantes para um fluxo de pagamento avulso. No mínimo, monitore:
Sempre cumpra o pedido com base no payment.succeeded do webhook, e 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 digitais com chaves de licença, processe também license_key.created. Para ver a lista completa de eventos — incluindo eventos de assinatura, entitlement, crédito, recuperação e cobrança — consulte o Guia de eventos de webhook. Você pode consultar este projeto com uma implementação de demonstração no GitHub usando Next.js e TypeScript. Você pode conferir a implementação em produção aqui.

Principais informações sobre checkout e moeda

Os valores dinâmicos (Pay-What-You-Want) estão na moeda base do produto — não em uma moeda local arbitrária — e a moeda base é limitada a USD, INR, GBP e EUR. Para cobrar um valor fixo em outra moeda (por exemplo, PHP), não é possível passá-lo diretamente: use Adaptive Pricing (converte o valor base usando o câmbio em tempo real) ou Localized Pricing (preço fixo por moeda, mas incompatível com Pay-What-You-Want).
Defina a moeda explicitamente. Passe billing_currency e billing_address.country na sessão de checkout. Se omitidos, a moeda e o país serão detectados a partir do IP do cliente (Adaptive Currency) e podem não corresponder ao que você pretende cobrar.
As sessões de checkout expiram em 24 horas (15 minutos quando confirm: true), e cada checkout_url é de uso único — gere uma nova sessão para cada cliente e tentativa de pagamento, em vez de reutilizar um link.
Compra repetida com um clique. Para um cliente recorrente com um método de pagamento salvo, passe payment_method_id junto com confirm: true para cobrar instantaneamente, ignorando completamente a seleção do método.

Referência de API relacionada

Create Checkout Session

Referência da API para criar sessões de checkout hospedadas e seguras para pagamentos avulsos e assinaturas

Create Payment Link

Referência da API para criar links de pagamento dinâmicos programaticamente
Última modificação em 6 de agosto de 2026