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 e produtos de assinatura na mesma sessão.
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.
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 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.
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_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 desnecessários.
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.
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.
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 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.
As respostas dos clientes 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: 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 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

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.
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: true para ir diretamente à página de pagamento.
A migração é simples: atualize sua integração para usar a API de Checkout Sessions ou o método do SDK, ajuste o payload da requisição para corresponder ao formato de Checkout Sessions e pronto. Não é necessário nenhum tratamento adicional.

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 26 de setembro de 2026