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.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 e produtos de assinatura na mesma sessão.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.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 moeda padrão do produto será usada.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
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
string
Método de pagamento salvo pertencente ao cliente vinculado. 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. Use o payment_id retornado.boolean
padrão:"false"
Se true, retorna uma URL de checkout encurtada em vez da URL completa da sessão.
string
ID da coleção de produtos para o fluxo de checkout baseado em coleções. Ao defini-lo, envie um array
product_cart vazio. Códigos de desconto não podem ser aplicados previamente na criação da sessão. Consulte Product Collections.string
Tax ID do cliente (por exemplo, um número de VAT). Requer
billing_address com um country.string
Nome comercial ou legal opcional associado ao Tax ID, com até 250 caracteres. Quando fornecido junto com um
tax_id válido, ele é exibido na invoice em vez do nome pessoal do cliente.integer
Substitua o limite mínimo de mandate no nível do merchant (em paise de INR) para e-mandates de INR em cartões indianos.O valor do mandate enviado ao processador é
max(this_floor, actual_billing_amount), portanto este é efetivamente o limite de autorização exibido ao cliente sempre que o valor da cobrança for menor. Quando não definido, a configuração do merchant se aplica; quando ela também não estiver definida, aplica-se o padrão do sistema de ₹15,000.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 clientes durante o checkout usando campos personalizados de formulário. Você pode definir até 5 campos personalizados por sessão de checkout. As respostas dos clientes 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: 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 produto único
Carrinho com vários produtos
Assinatura com período de trial
Checkout pré-confirmado
Checkout com substituição de moeda
Métodos de pagamento salvos para clientes recorrentes
Checkout B2B com coleta de Tax ID
Checkout com tema escuro e códigos de desconto acumulados
Métodos de pagamento regionais (UPI para a Índia)
Para obter informações detalhadas sobre configuração e testes de UPI, consulte a página India Payment Methods.Checkout BNPL (Buy Now Pay Later)
Para obter informações detalhadas sobre configuração e testes de 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çar um idioma
Coletar campos personalizados
Visualizar 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ço no seu site.O
current_breakup.subtotal visualizado já reflete a Purchasing Power Parity e o Charm Pricing quando aplicáveis ao produto.Quando o carrinho contém um produto de assinatura, a resposta da 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 de a assinatura ser criada. Ela é calculada em relação ao momento atual: now + trial period quando há um trial, caso contrário now + one payment frequency. O campo é omitido para carrinhos compostos apenas por compras únicas. Trata-se de uma estimativa baseada no horário 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 do trial, gratuito ou pago) e trial_amount (a cobrança por unidade do trial após descontos, nas unidades menores da moeda do preço). trial_amount só está presente para um paid trial e é null para um trial gratuito ou quando não há trial. Use current_breakup para obter o total com impostos efetivamente devido hoje.- Node.js SDK
- Python SDK
- REST API
Migrando de Dynamic Links
Se você usa Dynamic Links, as Checkout Sessions oferecem mais flexibilidade. Com Dynamic Links, era necessário fornecer o endereço de cobrança completo do cliente. Com Checkout Sessions, você pode enviar as informações disponíveis, e o fluxo de checkout coleta o restante. Por exemplo:- Forneça apenas o país de cobrança do cliente, e o checkout coleta os dados restantes.
- Ou forneça todas as informações e defina
confirm: truepara ir diretamente à página de pagamento.
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