Skip to main content

Quick Start

Create your first checkout session in under 5 minutes

API Reference

Full API documentation and interactive testing

Preview Endpoint

Calculate pricing and taxes before creating a session
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when confirm: true.
Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

Prerequisites

You need:
  • An active Dodo Payments merchant account
  • API credentials from Developer → API Keys in the dashboard
  • At least one product created in Products

Creating Your First Checkout Session

API Response

All methods return:
Only session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead. When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.

Redirect Your Customer

1

Extract the checkout URL

Get checkout_url from the API response.
2

Redirect to checkout

Send your customer to the URL:
Alternatively, open in a new window:
3

Handle the return

After payment, customers are redirected to your return_url with query parameters:Example redirect:
Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

Verificar o status da sessão

Para verificar o status de uma sessão, chame Get Checkout Session (GET /checkouts/{id}). A resposta contém a sessão id, created_at, customer_email e customer_name, além de payment_id e payment_status. Ambos os campos de pagamento são null enquanto o cliente ainda está inserindo os dados. Depois que o cliente envia o pagamento, payment_status contém o status do pagamento, como succeeded, failed ou processing. Use webhooks como fonte de verdade para o fulfillment.

Corpo da requisição

Campos obrigatórios

array
obrigatório
Array de produtos a serem incluídos na sessão de checkout. Cada produto deve ter um product_id válido do seu dashboard.Você pode combinar produtos de pagamento único com um produto de assinatura na mesma sessão. Um carrinho também pode conter dois ou mais produtos de assinatura, mas nesse caso não pode conter produtos de pagamento único. Consulte Carrinho com várias assinaturas. Um carrinho comporta no máximo 20 produtos.
Encontre os IDs dos seus produtos: você pode encontrar os IDs dos produtos no dashboard do Dodo Payments, em Products → View Details, ou usando a List Products API.

Campos opcionais

object
Informações do cliente. Você pode vincular um cliente existente usando o ID dele ou criar um novo registro de cliente durante o checkout.
object
Informações do endereço de cobrança para cálculo preciso de impostos, prevenção contra fraude e conformidade regulatória.Quando confirm: true, todos os campos do endereço de cobrança se tornam obrigatórios, a menos que minimal_address seja true.
array
Controle quais métodos de pagamento ficam disponíveis para os clientes durante o checkout. Isso ajuda a otimizar o checkout para mercados específicos ou requisitos comerciais.Opções comuns: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalConsulte a referência da Create Checkout Session API para ver a lista completa.
Sempre inclua credit e debit como opções alternativas para evitar falhas no checkout quando os métodos de pagamento preferidos estiverem indisponíveis.
Exemplo:
string
Substitua a seleção padrão de moeda por uma moeda de cobrança fixa. Usa códigos de moeda ISO 4217.Moedas compatíveis: USD, EUR, GBP, CAD, AUD, INR e outrasExemplo: "USD" para dólares americanos, "EUR" para eurosEste campo só tem efeito quando o adaptive pricing está habilitado. Se o adaptive pricing estiver desabilitado, a API descarta este campo, e a moeda vem do preço do produto ou do país de cobrança.
boolean
padrão:"false"
Exiba métodos de pagamento salvos anteriormente para clientes recorrentes, melhorando a velocidade do checkout e a experiência do usuário.
string
URL para redirecionar os clientes após a conclusão do pagamento. Dodo Payments adiciona parâmetros de consulta à sua URL durante o redirecionamento (consulte a tabela de redirecionamento acima).Exemplos de URLs de redirecionamento:
Use os parâmetros de consulta license_key e email para exibir chaves de licença ou enviar uma confirmação imediatamente na página de retorno, sem precisar de uma chamada de API adicional.
string
URL para redirecionar os clientes quando eles clicarem no botão voltar ou cancelarem a sessão de checkout. Se não for fornecida, o botão voltar não será exibido.Defina um cancel_url para oferecer aos clientes uma forma clara de retornar ao seu site sem concluir a compra.
boolean
padrão:"false"
Se true, finaliza imediatamente todos os detalhes da sessão. A API gera um erro se houver dados obrigatórios ausentes.Quando confirm: true:
  • Todos os campos do endereço de cobrança se tornam obrigatórios (somente country e zipcode quando minimal_address for true)
  • payment_method_id pode ser fornecido para processar a cobrança imediatamente
  • A sessão expira após 15 minutos em vez de 24 horas
  • Um customer_id existente é obrigatório se payment_method_id for fornecido
array
Aplique um ou mais códigos de desconto acumulados à sessão de checkout. Os códigos são aplicados na ordem do array (o primeiro código reduz o preço inicial, o segundo reduz o preço já com desconto e assim por diante), até o máximo de 20 códigos por sessão.Quando a Purchasing Power Parity está habilitada, o preço inicial é o valor ajustado pela PPP, não o preço base.
O campo singular discount_code abaixo está deprecated, mas continua totalmente compatível. Ele não pode ser combinado com discount_codes na mesma requisição.
string
obsoleto
Deprecated — prefira discount_codes para novas integrações. Este campo continua funcionando para compatibilidade retroativa, mas não pode ser combinado com discount_codes na mesma requisição.
object
Pares de chave-valor personalizados para armazenar informações adicionais sobre a sessão.
boolean
Substitua o comportamento padrão de 3DS do merchant para esta sessão.
boolean
padrão:"false"
Habilite o modo de coleta mínima de endereço. Quando habilitado, o checkout coleta apenas:
  • País: sempre obrigatório para determinar impostos
  • ZIP/Código postal: somente em regiões onde é necessário para calcular sales tax, VAT ou GST
Isso reduz significativamente o atrito no checkout ao eliminar campos de formulário desnecessários.Com confirm: true, somente zipcode (além de country) é obrigatório; os demais campos do endereço de cobrança continuam opcionais.
string
Um método de pagamento salvo pertencente ao customer anexado. Requer confirm: true e um customer.customer_id existente. O método de pagamento é validado quanto à elegibilidade usando a moeda do pagamento. Quando definido, a cobrança é processada imediatamente e checkout_url é retornado como null. Em vez disso, use o payment_id retornado.
Se true, retorna uma URL de checkout reduzida em vez da URL completa da sessão.
string
ID da coleção de produtos para o fluxo de checkout baseado em coleção. Ao defini-lo, passe um array product_cart vazio. Códigos de desconto não podem ser aplicados previamente na criação da sessão. Consulte Coleções de produtos.
string
ID fiscal do customer (por exemplo, um número de VAT). Requer billing_address com um country.
string
Nome comercial ou nome legal opcional associado ao ID fiscal, com até 250 caracteres. Quando fornecido junto com um tax_id válido, ele é exibido na invoice em vez do nome pessoal do customer.
integer
Substitua o limite mínimo de mandato no nível do merchant (em paise de INR) para e-mandates de INR em cartões indianos.O valor do mandato enviado ao processador é max(this_floor, actual_billing_amount), portanto este é efetivamente o limite de autorização exibido ao customer sempre que a cobrança for menor. Quando não definido, a configuração do merchant é aplicada; quando ela também não estiver definida, o padrão do sistema de ₹15.000 será aplicado.
object
Personalize a aparência e o comportamento da interface de checkout.
object
Configure recursos e comportamentos específicos para a sessão de checkout.
array
Colete informações adicionais dos customers durante o checkout usando campos de formulário personalizados. Você pode definir até 5 campos personalizados por sessão de checkout. As respostas dos customers são incluídas nos payloads de webhook e ficam disponíveis pela API.
As respostas dos customers aos campos personalizados são incluídas em:
  • Webhooks: payment.succeeded, subscription.active e outros payloads de eventos relevantes contêm o array custom_field_responses
  • Respostas da API: os objetos de pagamento e assinatura incluem custom_field_responses
object
Configuração adicional para sessões de checkout que contêm produtos de assinatura.

Exemplos de uso

Checkout simples de um único produto

Carrinho com vários produtos

Carrinho com várias assinaturas

Para vender vários produtos de assinatura em um único checkout, adicione dois ou mais produtos de assinatura ao product_cart. O customer paga uma vez, e Dodo Payments cria um pagamento, uma invoice e uma assinatura para cada produto. Cada assinatura tem seu próprio ciclo de cobrança e é renovada individualmente, portanto um produto mensal e um produto anual podem compartilhar um carrinho.
Um carrinho com várias assinaturas tem estes limites:
  • Ele não pode conter produtos de pagamento único. A API rejeita a solicitação com um 422.
  • Ele comporta no máximo 20 produtos de assinatura.
  • Ele não pode listar o mesmo produto duas vezes. Para vender mais de uma unidade de um produto, defina quantity.
  • Ele não pode usar cobrança sob demanda (subscription_data.on_demand).
  • Um código de desconto aplicado ao carrinho conta como um resgate.
subscription_data.trial_period_days aplica-se a todas as assinaturas do carrinho. Sem ele, cada assinatura usa a avaliação definida em seu próprio produto. Quando você não o define e Impedir uso indevido da avaliação está habilitado, um produto que o customer já avaliou começa sem avaliação. O pagamento resultante tem is_multi_subscription: true e lista todas as assinaturas iniciadas em subscription_ids. Seu subscription_id é null, pois nenhuma assinatura individual é proprietária do pagamento. O webhook payment.succeeded transporta os mesmos campos. Leia is_multi_subscription para encontrar o tipo de pagamento, não o tamanho de subscription_ids. Após o sucesso do pagamento, você recebe um evento payment.succeeded para o carrinho e um evento subscription.active para cada assinatura. A partir daí, cada assinatura é renovada, muda de plano e é cancelada individualmente, com sua própria invoice para cada renovação. Todas as assinaturas de um carrinho compartilham o método de pagamento usado pelo customer no checkout. Quando você atualiza o método de pagamento de uma delas, Dodo Payments move o novo método de pagamento para todas as assinaturas do mesmo carrinho que têm a mesma moeda de liquidação e moeda de cobrança e são active, on_hold, past_due ou paused. Todas as assinaturas de um carrinho começam com a mesma moeda de liquidação e moeda de cobrança, mesmo quando seus produtos têm moedas de preço diferentes. Uma alteração posterior, como uma mudança de plano, pode mover uma assinatura para outra moeda de liquidação ou moeda de cobrança. Essa assinatura mantém seu método de pagamento antigo, portanto atualize-o separadamente. Para uma assinatura on_hold, a atualização tenta novamente somente a invoice não paga dessa assinatura.

Assinatura com período de avaliação

Checkout pré-confirmado

Checkout com substituição de moeda

Métodos de pagamento salvos para customers recorrentes

Checkout B2B com coleta de Tax ID

Checkout com tema escuro e códigos de desconto empilhados

Métodos de pagamento regionais (UPI para a Índia)

Para obter informações detalhadas sobre a configuração e os testes do UPI, consulte a página Métodos de pagamento na Índia.

Checkout BNPL (Buy Now Pay Later)

Para obter informações detalhadas sobre a configuração e os testes do BNPL, consulte a página Buy Now Pay Later (BNPL).

Checkout instantâneo com método de pagamento existente

Ignorar a página de sucesso do pagamento com redirecionamento imediato

Forçando um idioma

Coleta de campos personalizados

Visualização das sessões de checkout

Use o endpoint Preview Checkout Session para calcular preços, impostos e totais antes de criar uma sessão. Isso é útil para exibir informações precisas de preços no seu site.
O current_breakup.subtotal visualizado já reflete Paridade do poder de compra e Charm Pricing quando aplicáveis ao produto.
Quando o carrinho contém um produto de assinatura, a resposta de visualização também retorna um next_billing_date — uma visualização da próxima data de cobrança, para que você possa exibi-la antes da criação da assinatura. Ela é calculada em relação ao momento atual: now + trial period quando uma avaliação se aplica; caso contrário, now + one payment frequency. O campo é omitido para carrinhos somente com produtos de pagamento único. Esta é uma estimativa baseada no momento da visualização; o next_billing_date oficial é definido quando a assinatura é ativada.
A visualização também retorna trial_period_days (a duração efetiva da avaliação, gratuita ou paga) e trial_amount (a cobrança da avaliação por unidade após descontos, nas unidades menores da moeda do preço). trial_amount só está presente para uma avaliação paga e é null para uma avaliação gratuita ou quando não há avaliação. Use current_breakup para obter o total com impostos efetivamente devido hoje.
Para um carrinho com várias assinaturas, a resposta também retorna um array subscriptions com uma entrada por assinatura: product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days e next_billing_date. O next_billing_date de nível superior é a data mais antiga do carrinho, e trial_period_days e trial_amount de nível superior são null. Leia os valores de subscriptions e current_breakup. recurring_breakup soma os valores de renovação de todas as assinaturas, mesmo quando elas são renovadas em datas diferentes; portanto, leia cada renovação de subscriptions.
Se você estiver usando Dynamic Links, as Checkout Sessions oferecem mais flexibilidade. Com Dynamic Links, era necessário fornecer o endereço de cobrança completo do customer. Com Checkout Sessions, você pode enviar as informações que tiver, e o fluxo de checkout coleta o restante. Por exemplo:
  • Forneça somente o país de cobrança do customer, e o checkout coletará os detalhes restantes.
  • Ou forneça todas as informações e defina confirm: true para ir diretamente à página de pagamento.
A migração é simples: atualize sua integração para usar a API ou o método do SDK de Checkout Sessions, ajuste o payload da solicitação para corresponder ao formato de Checkout Sessions e pronto. Nenhum tratamento adicional é necessário.

Recursos relacionados

Overlay Checkout

Abra o checkout como uma sobreposição modal na sua página

Inline Checkout

Incorpore o checkout diretamente na sua página

Mobile Integration

Integre o checkout em aplicativos móveis nativos

Webhooks

Monitore eventos de pagamento e assinatura

Payment Methods

Métodos de pagamento compatíveis por região

Subscriptions

Cobrança recorrente e gerenciamento de assinaturas
Última modificação em 8 de outubro de 2026