Checkout Sessions
Payment Links
Webhooks
API Reference
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.
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 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:
Tratar erros
Quando uma solicitação falha, a API retorna um código de status HTTP e um corpo JSON com umcode 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.
Payment Links
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â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 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.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 flagdisable... correspondente como true:
Exemplo de link de pagamento estático
Links de pagamento dinâmicos (obsoleto)
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 único. Para assinaturas, consulte o Subscription Integration Guide.
- Node.js SDK
- Python SDK
- Go SDK
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 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 único:
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, passebilling_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 seupayment_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.