Quick Start
API Reference
Preview Endpoint
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when
confirm: true.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
- Node.js SDK
- Python SDK
- REST API
API Response
All methods return: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:
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.Campos opcionais
Customer Information
Customer Information
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.
- Attach Existing Customer
- Create New Customer
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.Payment Configuration
Payment Configuration
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.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.
Session Management
Session Management
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
countryezipcodequandominimal_addressfortrue) payment_method_idpode ser fornecido para processar a cobrança imediatamente- A sessão expira após 15 minutos em vez de 24 horas
- Um
customer_idexistente é obrigatório sepayment_method_idfor 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
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.boolean
padrão:"false"
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.UI Customization
UI Customization
object
Personalize a aparência e o comportamento da interface de checkout.
Feature Flags
Feature Flags
object
Configure recursos e comportamentos específicos para a sessão de checkout.
Custom Fields
Custom Fields
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.
- Webhooks:
payment.succeeded,subscription.activee outros payloads de eventos relevantes contêm o arraycustom_field_responses - Respostas da API: os objetos de pagamento e assinatura incluem
custom_field_responses
Subscription Configuration
Subscription Configuration
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 aoproduct_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.
- 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
Links curtos para URLs de pagamento mais limpas
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.- Node.js SDK
- Python SDK
- REST API
Migração de Dynamic Links
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: truepara ir diretamente à página de pagamento.