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 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 ocheckout_url retornado.
Criar uma sessão de checkout
- Node.js SDK
- Python SDK
- cURL
Redirecionar para o checkout
Depois de criar uma sessão, redirecione o cliente para ocheckout_url:
Links de pagamento
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âmetrosession, para que uma atualização da página os mantenha.
Links de pagamento estáticos
Um link de pagamento estático é uma URL que você cria uma vez e compartilha várias vezes. A URL base é: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.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 sinalizadordisable... correspondente como true:
Exemplo de link de pagamento estático
Links de pagamento dinâmicos (obsoletos)
Para integrações existentes que usam links de pagamento dinâmicos, passepayment_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.
- Node.js SDK
- Python SDK
- Go SDK
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 ambienteDODO_PAYMENTS_WEBHOOK_KEY.
Veja um exemplo usando Next.js:
app/api/webhooks/dodo/route.ts
Eventos a serem monitorados
No mínimo, monitore estes eventos em um fluxo de pagamento avulso:
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, passebilling_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 opayment_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.