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
- Navigate to the Dodo Payments Dashboard
- 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.
-
Generate your API key:
- Go to Developer > API
- Detailed Guide
- Copy the API key the in env named DODO_PAYMENTS_API_KEY
-
Configure webhooks:
- Go to Developer > Webhooks
- Create a webhook URL for payment notifications
- Copy the webhook secret key in env
Integration
Payment Links
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_urlao 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 paracheckout_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.
- Node.js SDK
- Python SDK
- REST API
2
Redirect customer to checkout
Após criar a sessão, redirecione para
checkout_url para iniciar o fluxo hospedado.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.4. Static Payment Links
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:
-
integerpadrão:"1"Número de itens a comprar.
-
stringobrigatórioURL para redirecionar após a conclusão do pagamento.
A URL de redirecionamento incluirá os detalhes do pagamento como query parameters, por exemplo:
Se o produto tiver chaves de licença habilitadas, um parâmetro
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.comSe 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.com3
Pre-fill customer information (optional)
Adicione campos do cliente ou de cobrança como query parameters para agilizar o checkout.
Supported Customer Fields
Supported Customer Fields
-
stringNome completo do cliente (ignorado se firstName ou lastName for fornecido).
-
stringNome do cliente.
-
stringSobrenome do cliente.
-
stringEndereço de e-mail do cliente.
-
stringPaís do cliente.
-
stringEndereço.
-
stringCidade.
-
stringEstado ou província.
-
stringCódigo postal/ZIP.
-
booleantrue 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).
disable… correspondente como true:- Disable Flags Table
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)
-
stringEspecifica a moeda do pagamento. O padrão é a moeda do país de cobrança.
-
booleanpadrão:"true"Mostra ou oculta o seletor de moedas.
-
numberDefine o valor cobrado, em unidades principais da moeda (por exemplo,
12.5para 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. -
stringCampos de metadados personalizados (por exemplo,
metadata_orderId=123).
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.
4. Links de pagamento dinâmicos
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:- API de links de pagamento avulso Referência da API
- API de links de pagamento de assinatura Referência da API
Certifique-se de passar
payment_link = true para obter o link de pagamento - Node.js SDK
- Python SDK
- Go SDK
- Api Reference
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:Eventos a serem monitorados
Ativepayload.type e processe os eventos relevantes para um fluxo de pagamento avulso. No mínimo, monitore:
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
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