Checkout Sessions

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.

Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

Single-Use Links: The checkout_url returned by the API is not reusable and expires within 24 hours (or 15 minutes when confirm=true). It is intended for a single customer to complete one payment. Generate a fresh checkout session for each customer and each payment attempt rather than sharing or reusing a link.

Prerequisites

Dodo Payments Account

You’ll need an active Dodo Payments merchant account with API access.

API Credentials

Generate your API credentials from the Dodo Payments dashboard:

Products Setup

Create your products in the Dodo Payments dashboard before implementing checkout sessions.

Creating Your First Checkout Session

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'pdt_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.create(
            # Products to sell - use IDs from your Dodo Payments dashboard
            product_cart=[
                {
                    "product_id": "pdt_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout friction
            customer={
                "email": "customer@example.com",
                "name": "John Doe",
                "phone_number": "+1234567890"
            },
            
            # Billing address for tax calculation and compliance
            billing_address={
                "street": "123 Main St",
                "city": "San Francisco", 
                "state": "CA",
                "country": "US",  # Required: ISO 3166-1 alpha-2 country code
                "zipcode": "94102"
            },
            
            # Where to redirect after successful payment
            return_url="https://yoursite.com/checkout/success",
            
            # Custom data for your internal tracking
            metadata={
                "order_id": "order_123",
                "source": "web_app"
            }
        )
        
        # Redirect your customer to this URL to complete payment
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // Products to sell - use IDs from your Dodo Payments dashboard
        product_cart: [
          {
            product_id: 'pdt_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout friction
        customer: {
          email: 'customer@example.com',
          name: 'John Doe',
          phone_number: '+1234567890'
        },
        
        // Billing address for tax calculation and compliance
        billing_address: {
          street: '123 Main St',
          city: 'San Francisco',
          state: 'CA', 
          country: 'US', // Required: ISO 3166-1 alpha-2 country code
          zipcode: '94102'
        },
        
        // Where to redirect after successful payment
        return_url: 'https://yoursite.com/checkout/success',
        
        // Custom data for your internal tracking
        metadata: {
          order_id: 'order_123',
          source: 'web_app'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

API Response

All methods above return the same response structure:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Somente session_id tem presença garantida. Dois casos retornam campos adicionais ou em menor quantidade:

payment_method_id foi fornecido — a cobrança é processada imediatamente e checkout_url é null. Use o payment_id retornado.
confirm: true criou o pagamento no momento da criação da sessão — a resposta também inclui payment_id, client_secret e publishable_key para uso com o SDK de checkout do Dodo Payments.

O checkout_url gerado é de uso único e expira em até 24 horas. Não o armazene em cache nem o reutilize entre clientes ou tentativas de pagamento — crie uma nova sessão de checkout sempre que precisar de um link atualizado.

Get the checkout URL

Extraia o checkout_url da resposta da API.

Redirect your customer

Direcione seu cliente para a URL de checkout para concluir a compra.

// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');

Opções alternativas de integração: em vez de redirecionar, você pode incorporar o checkout diretamente à sua página usando Overlay Checkout (sobreposição modal) ou Inline Checkout (totalmente incorporado). Em um aplicativo móvel nativo, encaminhe a mesma URL para os Mobile Checkout SDKs para Android, iOS, React Native ou Flutter. Todos eles usam a mesma URL de sessão de checkout.

Handle the return

Após o pagamento, os clientes são redirecionados para seu return_url com parâmetros de consulta que incluem o ID do pagamento/assinatura, o status, o e-mail do cliente e quaisquer chaves de licença. Consulte a documentação dos parâmetros de return_url para ver a lista completa.

Corpo da solicitação

Required Fields

Campos essenciais necessários para cada sessão de checkout

Optional Fields

Configuração adicional para personalizar sua experiência de checkout

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 painel do Dodo Payments.

Checkout misto: você pode combinar produtos de pagamento único e produtos de assinatura na mesma sessão de checkout. Isso permite casos de uso avançados, como taxas de configuração com assinaturas, pacotes de hardware com SaaS e muito mais.

Mostrar Product Cart Item Properties

string

obrigatório

O identificador exclusivo do produto no seu painel do Dodo Payments.Exemplo: "pdt_123abc456def"

integer

obrigatório

Quantidade do produto.Exemplo: 1 para um item, 3 para várias unidades

array

Array de complementos a serem associados ao produto. Válido somente se o produto for uma assinatura.

Mostrar Addon item properties

string

obrigatório

integer

obrigatório

integer

Valor pago pelo cliente quando pay_what_you_want está habilitado. Se estiver desabilitado, este campo será ignorado.Formato: representado na menor denominação da moeda (por exemplo, centavos para USD). Para cobrar US$ 1,00, passe 100.

array

Substituições por sessão de checkout para concessões de créditos já associadas a este produto. Use isso para conceder uma quantidade diferente de créditos nesta sessão específica — por exemplo, um pacote promocional que concede 1.000 créditos de API em vez dos 500 padrão do produto — sem criar um produto separado.

Cada credit_entitlement_id já deve estar associado ao produto. Este campo substitui apenas o credits_amount concedido quando esta sessão é cumprida; as configurações de concessão de créditos no nível do produto (expiração, rollover etc.) continuam sendo aplicadas.

Mostrar Credit entitlement override properties

string

obrigatório

ID da concessão de crédito a substituir. Já deve estar associada ao produto.

string

obrigatório

Número de créditos a conceder nesta sessão de checkout, substituindo o credits_amount no nível do produto. Deve ser maior que zero.

Encontre os IDs dos seus produtos: você pode encontrar os IDs dos produtos no painel do Dodo Payments, em Products → View Details, ou usando a List Products API.

Campos opcionais

Configure estes campos para personalizar a experiência de checkout e adicionar lógica de negócios ao seu fluxo de pagamento.

Customer Information

object

Informações do cliente. Você pode associar um cliente existente usando o ID dele ou criar um novo registro de cliente durante o checkout.

Attach Existing Customer
New Customer

Associe um cliente existente à sessão de checkout usando o ID dele.

Mostrar Existing Customer Properties

string

obrigatório

O identificador exclusivo de um cliente existente. Use-o para associar a sessão de checkout a um cliente existente em vez de criar um novo.

Crie um novo registro de cliente durante o checkout.

Mostrar New Customer Properties

string

obrigatório

Endereço de e-mail do cliente. Obrigatório ao criar um novo cliente.

string

Nome completo do cliente, conforme deve aparecer em recibos e faturas.Exemplo: "John Doe" ou "Jane Smith"

string

Número de telefone do cliente no formato internacional. Obrigatório para alguns métodos de pagamento e para prevenção contra fraudes.Formato: inclua o código do país, por exemplo, "+1234567890" para números dos EUA

object

Informações do endereço de cobrança para cálculo preciso de impostos, prevenção contra fraudes e conformidade regulatória.

Quando confirm é definido como true, todos os campos do endereço de cobrança se tornam obrigatórios para a criação bem-sucedida da sessão.

Mostrar Billing address object properties

string

Endereço completo, incluindo número da residência, nome da rua e número do apartamento/unidade, quando aplicável.Exemplo: "123 Main St, Apt 4B" ou "456 Oak Avenue"

string

Nome da cidade ou município.Exemplo: "San Francisco", "New York", "London"

string

Nome do estado, província ou região. Use nomes completos ou abreviações padrão.Exemplo: "California" ou "CA", "Ontario" ou "ON"

string

obrigatório

Código de país ISO de duas letras (ISO 3166-1 alpha-2). Este campo é sempre obrigatório quando billing_address é fornecido.Exemplos: "US" (Estados Unidos), "CA" (Canadá), "GB" (Reino Unido), "DE" (Alemanha)

Country Code Reference

Ver a lista completa de países compatíveis e seus códigos ISO

string

Código postal, ZIP code ou equivalente, conforme os requisitos do país.Exemplos: "94102" (EUA), "M5V 3A8" (Canadá), "SW1A 1AA" (Reino Unido)

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, paypal. Este não é o conjunto completo — consulte a referência da API Create Checkout Session para ver todos os valores aceitos.

Importante: 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:

["apple_pay", "google_pay", "credit", "debit"]

string

Substitua a seleção de moeda padrão 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 euros

Este campo só tem efeito quando o Adaptive Currency está habilitado. Se o Adaptive Currency 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

string

URL para redirecionar os clientes após a conclusão do pagamento. O Dodo Payments adiciona os seguintes parâmetros de consulta à sua URL durante o redirecionamento:

Parâmetro	Tipo	Condição
`payment_id`	`string`	Sempre presente para pagamentos únicos
`subscription_id`	`string`	Sempre presente para pagamentos de assinatura
`status`	`string`	Sempre presente
`license_key`	`string`	Presente se o produto tiver chaves de licença habilitadas. Separado por vírgulas quando houver várias chaves
`email`	`string`	Presente se o cliente tiver um e-mail registrado

Exemplos de URLs de redirecionamento:

# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com

Use os parâmetros de consulta license_key e email para exibir chaves de licença ou enviar uma confirmação imediatamente na sua página de retorno, sem precisar de uma chamada de API adicional.

string

URL para redirecionar os clientes quando eles clicarem no botão de voltar ou cancelarem a sessão de checkout. Se não for fornecida, o botão de voltar não será exibido.

Defina uma cancel_url para oferecer aos clientes uma maneira clara de retornar ao seu site sem concluir a compra. Isso melhora a experiência de checkout e reduz o atrito.

boolean

padrão:"false"

Se for true, finaliza imediatamente todos os detalhes da sessão. A API lançará um erro se houver dados obrigatórios ausentes.

array

Aplique um ou mais códigos de desconto em sequência à sessão de checkout. Os códigos são aplicados na ordem do array (o primeiro código reduz o preço-base, o segundo reduz o preço já descontado e assim por diante), até o máximo de 20 códigos por sessão.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

O campo singular discount_code abaixo está obsoleto, mas ainda é totalmente compatível — as integrações existentes continuam funcionando sem alterações. Ele não pode ser combinado com discount_codes na mesma solicitação. Migre para discount_codes quando for conveniente para aproveitar a aplicação em sequência.

string

obsoleto

Obsoleto — 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 solicitaçã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 comerciante 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 a determinação de impostos
ZIP/Código postal: somente em regiões onde é necessário para o cálculo de sales tax, VAT ou GST

Isso reduz significativamente o atrito no checkout ao eliminar campos de formulário desnecessários.

Habilite o endereço mínimo para concluir o checkout mais rapidamente. A coleta do endereço completo continua disponível para empresas que exigem detalhes completos de cobrança.

string

Um método de pagamento salvo pertencente ao cliente associado. Requer confirm: true e um customer.customer_id existente. Quando definido, a cobrança é processada imediatamente e checkout_url é retornado como null — use o payment_id retornado.

boolean

padrão:"false"

Se for 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ção.

string

ID fiscal do cliente (por exemplo, um número de VAT). Requer billing_address com um country.

string

Nome comercial ou jurídico opcional associado ao ID fiscal. Quando fornecido juntamente com um tax_id válido, ele é exibido na fatura em vez do nome pessoal do cliente.

integer

Substitua o limite mínimo de mandato no nível do comerciante (em paise de INR) para e-mandates de INR em cartões indianos.

UI Customization & Features

object

Personalize a aparência e o comportamento da interface de checkout.

Mostrar Customization object properties

string

padrão:"system"

Tema da interface de checkout. Opções: light, dark ou system.

boolean

padrão:"true"

Exiba a seção de detalhes do pedido na interface de checkout.

boolean

padrão:"true"

Exiba a tag “on-demand” para produtos aplicáveis.

string

Force a interface de checkout a ser exibida em um idioma específico. Por padrão, o checkout detecta automaticamente o idioma do navegador do cliente.Códigos de idioma compatíveis: ar (árabe), ca (catalão), de (alemão), en (inglês), es (espanhol), fr (francês), he (hebraico), id (indonésio), it (italiano), ja (japonês), ko (coreano), ms (malaio), nl (holandês), pl (polonês), pt (português), ro (romeno), ru (russo), sv (sueco), th (tailandês), tr (turco), zh (chinês)Exemplo: "es" para espanhol, "ja" para japonês

object

Configuração de tema personalizada com cores para os modos claro e escuro, fontes e estilo de botões. Esta é a substituição no lado do servidor para a opção themeConfig obsoleta no lado do cliente.

Mostrar Theme config properties

object

Configuração de cores do modo claro.

object

Configuração de cores do modo escuro.

string

URL da fonte principal. Deve ser uma URL https:// válida.

string

URL da fonte secundária. Deve ser uma URL https:// válida.

string

Tamanho da fonte da interface de checkout. Opções: xs, sm, md, lg, xl, 2xl.

string

Peso da fonte da interface de checkout. Opções: normal, medium, bold, extraBold.

string

Texto personalizado para o botão de pagamento (por exemplo, "Complete Purchase" ou "Subscribe Now"). Máximo de 100 caracteres.

string

Raio da borda dos elementos da interface. Um número seguido por px, rem ou em (por exemplo, "4px", "0.5rem", "1em").

object

Configure recursos e comportamentos específicos para a sessão de checkout.

Mostrar Feature flags object properties

boolean

padrão:"true"

Permita que os clientes selecionem a moeda preferida durante o checkout.

boolean

padrão:"true"

Exiba o campo de código de desconto na interface de checkout.

boolean

padrão:"false"

Permita que os clientes adicionem ou removam complementos de um produto de assinatura durante o checkout. Aplica-se somente a produtos de assinatura.

boolean

padrão:"true"

Colete os números de telefone dos clientes durante o checkout.

boolean

padrão:"false"

Exija que o cliente forneça um número de telefone para concluir o checkout. Requer que allow_phone_number_collection também seja true.

boolean

padrão:"true"

Permita que os clientes informem números de identificação fiscal.

boolean

padrão:"false"

Force a criação de um novo registro de cliente em vez de atualizar registros existentes.

boolean

Permita que os clientes editem o endereço de e-mail durante o checkout.

boolean

Permita que os clientes editem o nome durante o checkout.

boolean

Permita que os clientes editem o endereço da rua durante o checkout.

boolean

Permita que os clientes editem a cidade durante o checkout.

boolean

Permita que os clientes editem o estado durante o checkout.

boolean

Permita que os clientes editem o país durante o checkout.

boolean

Permita que os clientes editem o código postal durante o checkout.

boolean

Permita que os clientes informem ou editem seu ID fiscal durante o checkout.

boolean

padrão:"false"

Permita que o cliente informe ou edite o nome comercial associado ao ID fiscal. Funciona independentemente de allow_customer_editing_tax_id — qualquer uma das flags (ou allow_tax_id) é suficiente. Normalmente, é definido junto com allow_customer_editing_tax_id.

boolean

padrão:"false"

Ignore a página padrão de sucesso do pagamento e redirecione os clientes imediatamente para seu return_url após a conclusão do pagamento.

Use isso quando tiver uma página de sucesso personalizada que ofereça uma experiência melhor ao usuário ou para aplicativos móveis e fluxos de checkout incorporados.

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.

Mostrar Custom field object properties

string

obrigatório

Identificador exclusivo deste campo. Usado como chave nos payloads de webhook e nas respostas da API.Exemplo: "company_name", "referral_source", "team_size"

string

obrigatório

Rótulo exibido ao cliente no formulário de checkout.Exemplo: "Company Name", "How did you hear about us?", "Team Size"

string

obrigatório

Tipo de campo que determina as regras de validação da entrada.Tipos disponíveis:

text - Campo de texto de uma linha
number - Entrada numérica
email - Endereço de e-mail com validação
url - URL com validação
date - Seletor de data
dropdown - Seleção entre opções predefinidas
boolean - Alternância Sim/Não

boolean

padrão:"false"

Indica se este campo deve ser preenchido antes que o checkout possa ser concluído.

string

Texto de placeholder exibido no campo de entrada.

array

Lista de opções para o tipo de campo dropdown. Obrigatória quando field_type é dropdown; ignorada para os demais tipos.Exemplo: ["Google", "Twitter", "Friend referral", "Other"]

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: os objetos de pagamento e assinatura incluem custom_field_responses

Subscription Configuration

object

Configuração adicional para sessões de checkout que contêm produtos de assinatura.

Mostrar Subscription data object properties

integer

Número de dias do período de teste antes da primeira cobrança. Deve estar entre 0 e 10.000 dias.Não é possível definir um valor de teste pago por sessão — configure trial_amount no preço recorrente do produto. Consulte Testes pagos.

object

Configuração de assinatura on-demand para cobrança baseada em uso ou medição.

Mostrar On-demand object properties

boolean

obrigatório

Se definido como true, não realiza nenhuma cobrança e apenas autoriza os dados do método de pagamento para uso futuro.

integer

Preço do produto para a cobrança inicial do cliente. Se não for especificado, será usado o preço armazenado do produto.Formato: representado na menor denominação da moeda (por exemplo, centavos para USD). Para cobrar US$ 1,00, passe 100.

string

Moeda opcional do preço do produto. Se não for especificada, usa como padrão a moeda do produto.

string

Substituição opcional da descrição do produto para cobrança e itens de linha. Se não for especificada, será usada a descrição armazenada do produto.

boolean

Indica se as tarifas de Adaptive Currency devem ser incluídas no preço do produto (true) ou adicionadas posteriormente (false). Ignorado se a precificação adaptativa não estiver habilitada.

Exemplos de uso

Veja 10 exemplos completos que apresentam diferentes configurações de sessões de checkout para vários cenários comerciais:

1. Checkout simples de um único produto

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. Carrinho com vários produtos

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_laptop',
      quantity: 1
    },
    {
      product_id: 'pdt_mouse',
      quantity: 2
    },
    {
      product_id: 'pdt_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. Assinatura com período de teste

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. Checkout pré-confirmado

Quando confirm é definido como true, o cliente é levado diretamente à página de checkout, ignorando todas as etapas de confirmação.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. Checkout com substituição de moeda

A substituição de billing_currency só entra em vigor quando o Adaptive Currency está habilitado nas configurações da sua conta. Se o Adaptive Currency estiver desabilitado, este parâmetro não terá efeito.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. Métodos de pagamento salvos para clientes recorrentes

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. Checkout B2B com coleta de ID fiscal

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

8. Checkout com tema escuro e códigos de desconto em sequência

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['BLACKFRIDAY2024'],
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

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

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. Checkout BNPL (Buy Now Pay Later)

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

11. Uso de métodos de pagamento existentes para checkout instantâneo

Use o método de pagamento salvo de um cliente para criar uma sessão de checkout que seja processada imediatamente, ignorando a coleta do método de pagamento:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});

Ao usar payment_method_id, confirm deve ser definido como true e um customer_id existente deve ser fornecido. O método de pagamento será validado quanto à elegibilidade com a moeda do pagamento. Como a cobrança é processada imediatamente, checkout_url é retornado como null — use o payment_id retornado.

O método de pagamento deve pertencer ao cliente e ser compatível com a moeda do pagamento. Isso permite compras com um clique para clientes recorrentes.

12. Links curtos para URLs de pagamento mais limpas

Gere links de pagamento encurtados e compartilháveis com slugs personalizados:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123

Links curtos são perfeitos para compartilhamento por SMS, e-mail ou redes sociais. Eles são mais fáceis de memorizar e geram mais confiança nos clientes do que URLs longas.

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

Redirecione os clientes imediatamente após a conclusão do pagamento, ignorando a página de sucesso padrão:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});

Use redirect_immediately: true quando tiver uma página de sucesso personalizada que ofereça uma experiência melhor do que a página de sucesso padrão do pagamento. Isso é especialmente útil para aplicativos móveis e fluxos de checkout incorporados.

Quando redirect_immediately está habilitado, os clientes são redirecionados para seu return_url imediatamente após a conclusão do pagamento, ignorando completamente a página de sucesso padrão.

14. Forçar um idioma

Force o checkout a ser exibido em um idioma específico, substituindo a detecção do idioma do navegador do cliente:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});

Use force_language quando souber o idioma preferido do cliente (por exemplo, nas configurações da conta) ou ao segmentar mercados regionais específicos.

Idiomas compatíveis: árabe (ar), catalão (ca), chinês (zh), holandês (nl), inglês (en), francês (fr), alemão (de), hebraico (he), indonésio (id), italiano (it), japonês (ja), coreano (ko), malaio (ms), polonês (pl), português (pt), romeno (ro), russo (ru), espanhol (es), sueco (sv), tailandês (th), turco (tr)

15. Coletar campos personalizados

Colete informações adicionais dos clientes durante o checkout usando campos personalizados:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

As respostas dos campos personalizados são incluídas automaticamente nos payloads de webhook (payment.succeeded, subscription.active etc.) e podem ser recuperadas pela API. Use-as para enriquecer seu CRM, acionar fluxos de onboarding ou personalizar a experiência do cliente.

Tipos de campo disponíveis: text, number, email, url, date, dropdown, boolean

Visualizar sessões de checkout

Antes de criar uma sessão de checkout, você pode visualizar o detalhamento de preços, incluindo impostos, descontos e totais. Isso é útil para exibir preços precisos aos clientes antes que eles avancem para o checkout.

Quando o carrinho contém um produto de assinatura, a resposta de visualização também retorna um next_billing_date — uma prévia 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 há um período de teste; caso contrário, now + one payment frequency. O campo é omitido para carrinhos exclusivamente de compras únicas. 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 do período de teste, gratuito ou pago) e trial_amount (a cobrança de teste por unidade após os descontos, nas unidades menores da moeda do preço). trial_amount está presente somente para um teste pago e é null para um teste gratuito ou sem teste. Use current_breakup para obter o total tributado efetivamente devido hoje.

Node.js SDK
Python SDK

const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'pdt_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

console.log('Subtotal:', preview.current_breakup.subtotal);
console.log('Tax:', preview.current_breakup.tax);
console.log('Discount:', preview.current_breakup.discount);
console.log('Total:', preview.current_breakup.total_amount);

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

preview = client.checkout_sessions.preview(
    product_cart=[
        {"product_id": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

print(f"Subtotal: {preview.current_breakup.subtotal}")
print(f"Tax: {preview.current_breakup.tax}")
print(f"Discount: {preview.current_breakup.discount}")
print(f"Total: {preview.current_breakup.total_amount}")

# Present only when the cart contains a subscription product
print(f"Next billing date: {preview.next_billing_date}")

Preview API Reference

Veja a documentação completa do endpoint de visualização.

Migrar de Dynamic Links para Checkout Sessions

Principais diferenças

Anteriormente, ao criar um link de pagamento com Dynamic Links, era necessário fornecer o endereço de cobrança completo do cliente. Com Checkout Sessions, isso não é mais necessário. Você pode simplesmente enviar as informações que tiver, e cuidaremos do restante. Por exemplo:

Se você souber apenas o país de cobrança do cliente, forneça somente essa informação.
O fluxo de checkout coletará automaticamente os dados ausentes antes de levar o cliente à página de pagamento.
Por outro lado, se você já tiver todas as informações necessárias e quiser ir diretamente para a página de pagamento, poderá enviar o conjunto completo de dados e incluir confirm=true no corpo da solicitação.

Processo de migração

A migração de Dynamic Links para Checkout Sessions é simples:

Update your integration

Atualize sua integração para usar o novo método da API ou do SDK.

Adjust request payload

Ajuste o payload da solicitação de acordo com o formato de Checkout Sessions.

That's it!

Sim. Nenhum tratamento adicional ou etapa especial de migração é necessário da sua parte.

Referência da API relacionada

Create Checkout Session

Referência completa da API para criar sessões de checkout com todos os parâmetros e opções disponíveis

Preview Checkout Session

Referência da API para visualizar preços, impostos e totais antes de criar uma sessão

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

Prerequisites

Creating Your First Checkout Session

API Response

Corpo da solicitação

Required Fields

Optional Fields

Campos obrigatórios

Campos opcionais

Country Code Reference

Exemplos de uso

1. Checkout simples de um único produto

2. Carrinho com vários produtos

3. Assinatura com período de teste

4. Checkout pré-confirmado

5. Checkout com substituição de moeda

6. Métodos de pagamento salvos para clientes recorrentes

7. Checkout B2B com coleta de ID fiscal

8. Checkout com tema escuro e códigos de desconto em sequência

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

10. Checkout BNPL (Buy Now Pay Later)

11. Uso de métodos de pagamento existentes para checkout instantâneo

12. Links curtos para URLs de pagamento mais limpas

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

14. Forçar um idioma

15. Coletar campos personalizados

Visualizar sessões de checkout

Preview API Reference

Migrar de Dynamic Links para Checkout Sessions

Principais diferenças

Processo de migração

Referência da API relacionada

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​Prerequisites

​Creating Your First Checkout Session

​API Response

​Corpo da solicitação

Required Fields

Optional Fields

​Campos obrigatórios

​Campos opcionais

Country Code Reference

​Exemplos de uso

​1. Checkout simples de um único produto

​2. Carrinho com vários produtos

​3. Assinatura com período de teste

​4. Checkout pré-confirmado

​5. Checkout com substituição de moeda

​6. Métodos de pagamento salvos para clientes recorrentes

​7. Checkout B2B com coleta de ID fiscal

​8. Checkout com tema escuro e códigos de desconto em sequência

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

​10. Checkout BNPL (Buy Now Pay Later)

​11. Uso de métodos de pagamento existentes para checkout instantâneo

​12. Links curtos para URLs de pagamento mais limpas

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

​14. Forçar um idioma

​15. Coletar campos personalizados

​Visualizar sessões de checkout

Preview API Reference

​Migrar de Dynamic Links para Checkout Sessions

​Principais diferenças

​Processo de migração

​Referência da API relacionada

Create Checkout Session

Preview Checkout Session

Prerequisites

Creating Your First Checkout Session

API Response

Corpo da solicitação

Campos obrigatórios

Campos opcionais

Exemplos de uso

1. Checkout simples de um único produto

2. Carrinho com vários produtos

3. Assinatura com período de teste

4. Checkout pré-confirmado

5. Checkout com substituição de moeda

6. Métodos de pagamento salvos para clientes recorrentes

7. Checkout B2B com coleta de ID fiscal

8. Checkout com tema escuro e códigos de desconto em sequência

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

10. Checkout BNPL (Buy Now Pay Later)

11. Uso de métodos de pagamento existentes para checkout instantâneo

12. Links curtos para URLs de pagamento mais limpas

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

14. Forçar um idioma

15. Coletar campos personalizados

Visualizar sessões de checkout

Migrar de Dynamic Links para Checkout Sessions

Principais diferenças

Processo de migração

Referência da API relacionada