Checkout Sessions

Create secure, hosted checkout experiences that handle the complete payment flow for both one-time purchases and subscriptions with full customization control.

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.

​

Prerequisites

1. Dodo Payments Account

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

2. API Credentials

   Generate your API credentials from the Dodo Payments dashboard:

3. Products Setup

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

​

Creating Your First Checkout Session

Node.js SDK

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: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: '[e-mail]',
        name: 'John Doe',
        phone_number: '[phone]'
      },
      
      // 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' });
  }
});

Python SDK

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": "prod_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout friction
            customer={
                "email": "[e-mail]",
                "name": "John Doe",
                "phone_number": "[phone]"
            },
            
            # 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

REST API

// 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: 'prod_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout friction
        customer: {
          email: '[e-mail]',
          name: 'John Doe',
          phone_number: '[phone]'
        },
        
        // 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"
}

1. Get the checkout URL

   Extract the checkout_url from the API response.

2. Redirect your customer

   Direct your customer to the checkout URL to complete their purchase.

   // Redirect immediately
   window.location.href = session.checkout_url;
   
   // Or open in new window
   window.open(session.checkout_url, '_blank');
   

   Alternative Integration Options: Instead of redirecting, you can embed the checkout directly in your page using Overlay Checkout (modal overlay) or Inline Checkout (fully embedded). Both options use the same checkout session URL.

3. Handle the return

   After payment, customers are redirected to your return_url with query parameters including payment/subscription ID, status, customer email, and any license keys. See the return_url parameter docs for the full list.

​

Request Body

Required Fields

Essential fields needed for every checkout session

Optional Fields

Additional configuration to customize your checkout experience

​

Required Fields

product_cart · array · obrigatório

Array of products to include in the checkout session. Each product must have a valid product_id from your Dodo Payments dashboard.

Mixed Checkout: You can combine one-time payment products and subscription products in the same checkout session. This enables powerful use cases like setup fees with subscriptions, hardware bundles with SaaS, and more.

Mostrar Product Cart Item Properties

product_id · string · obrigatório

The unique identifier of the product from your Dodo Payments dashboard.

Example: "prod_123abc456def"

quantity · integer · obrigatório

Quantity of the product.

Example: 1 for single item, 3 for multiple quantities

addons · array

Array of addons to attach to the product. Only valid if the product is a subscription.

Mostrar Addon item properties

addon_id · string · obrigatório

quantity · integer · obrigatório

amount · integer

Amount the customer pays if pay_what_you_want is enabled. If disabled, this field will be ignored.

Formato: Representado na menor denominação da moeda (por exemplo, centavos para USD). Por exemplo, para cobrar $1.00, passe 100.

credit_entitlements · array

Substituições por sessão de checkout para direitos de crédito já associados a este produto. Use isso para conceder um número diferente de créditos para esta única sessão — 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 deve já estar anexado ao produto. Este campo substitui apenas o credits_amount concedido quando esta sessão é cumprida; as configurações de direito a crédito em nível de produto (expiração, acúmulo, etc.) ainda se aplicam.

Mostrar Credit entitlement override properties

credit_entitlement_id · string · obrigatório

ID do direito a crédito a ser substituído. Deve já estar anexado ao produto.

credits_amount · string · obrigatório

Número de créditos a serem concedidos para esta sessão de checkout, substituindo o credits_amount em nível de produto. Deve ser maior que zero.

Encontre seus IDs de Produto: Você pode encontrar os IDs de produtos no painel do Dodo Payments em Produtos → Ver Detalhes, ou usando o API Listar Produtos.

​

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

customer · object

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

Attach Existing Customer

Anexe um cliente existente à sessão de checkout usando seu ID.

Mostrar Existing Customer Properties

customer_id · string · obrigatório

O identificador único de um cliente existente. Use isso para anexar a sessão de checkout a um cliente existente, em vez de criar um novo.

New Customer

Crie um novo registro de cliente durante o checkout.

Mostrar New Customer Properties

email · string · obrigatório

Endereço de email do cliente. Necessário ao criar um novo cliente.

name · string

Nome completo do cliente conforme deve aparecer em recibos e faturas.

Exemplo: "John Doe" ou "Jane Smith"

phone_number · string

Número de telefone do cliente em formato internacional. Necessário para alguns métodos de pagamento e prevenção de fraudes.

Formato: Inclua o código do país, por exemplo, "[phone]" para números dos EUA

billing_address · object

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

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

Mostrar Billing address object properties

street · string

Endereço completo incluindo número da casa, nome da rua e número do apartamento/unidade, se aplicável.

Exemplo: "123 Main St, Apt 4B" ou "456 Oak Avenue"

city · string

Nome da cidade ou município.

Exemplo: "San Francisco", "New York", "London"

state · string

Nome do estado, província ou região. Use nomes completos ou abreviações padrão.

Exemplo: "California" ou "CA", "Ontario" ou "ON"

country · string · obrigatório

Código ISO de país de duas letras (ISO 3166-1 alpha-2). Este campo é sempre necessário quando endereço_de_cobrança é fornecido.

Exemplos: "US" (Estados Unidos), "CA" (Canadá), "GB" (Reino Unido), "DE" (Alemanha)

Country Code Reference

Veja a lista completa de países suportados e seus códigos ISO

zipcode · string

Código postal, CEP ou equivalente com base nos requisitos do país.

Exemplos: "94102" (EUA), "M5V 3A8" (Canadá), "SW1A 1AA" (Reino Unido)

Payment Configuration

allowed_payment_method_types · array

Controle quais métodos de pagamento estão disponíveis para clientes durante o checkout. Isso ajuda a otimizar para mercados específicos ou requisitos de negócios.

Opções Disponíveis: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal, sunbit

Crítico: Sempre inclua credit e debit como opções de fallback para evitar falhas no checkout quando métodos de pagamento preferidos não estão disponíveis.

Exemplo:

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

billing_currency · string

Substitua a seleção de moeda padrão com uma moeda de cobrança fixa. Usado códigos de moeda ISO 4217.

Moedas Suportadas: USD, EUR, GBP, CAD, AUD, INR, e mais

Exemplo: "USD" para Dólares Americanos, "EUR" para Euros

Este campo só é efetivo quando o precificação adaptativa está ativado. Se a precificação adaptativa estiver desativada, a moeda padrão do produto será usada.

show_saved_payment_methods · boolean · padrão: "false"

Exiba métodos de pagamento salvos anteriormente para clientes retornantes, melhorando a velocidade do checkout e a experiência do usuário.

Session Management

return_url · string

URL para redirecionar os clientes após a conclusão do pagamento. O aplicativo Dodo Payments anexa os seguintes parâmetros de consulta ao seu URL ao redirecionar:

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 ativadas. Separado por vírgulas se múltiplas chaves
email	string	Presente se o cliente tiver um email 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 em sua página de retorno, sem precisar de uma chamada de API extra.

cancel_url · string

URL para redirecionar clientes quando clicam no botão voltar ou cancelam a sessão de checkout. Se não for fornecido, o botão voltar não será exibido.

Defina um cancel_url para dar aos clientes um caminho claro para retornar ao seu site sem completar a compra. Isso melhora a experiência de checkout e reduz atritos.

confirm · boolean · padrão: "false"

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

discount_codes · array

Aplique um ou mais códigos de desconto empilhados à 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á com desconto e assim por diante), até um máximo de 20 códigos por sessão.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

O campo singular discount_code abaixo está obsoleto mas ainda totalmente suportado — integrações existentes continuam funcionando sem alterações. Não pode ser combinado com discount_codes na mesma solicitação. Migre para discount_codes quando conveniente para aproveitar as vantagens da empilhamento.

discount_code · string · obsoleto

Obsoleto — prefira discount_codes para novas integrações. Este campo ainda funciona para compatibilidade com versões anteriores, mas não pode ser combinado com discount_codes na mesma solicitação.

metadata · object

Pares de chave-valor personalizados para armazenar informações adicionais sobre a sessão.

force_3ds · boolean

Substitua o comportamento padrão do 3DS do comerciante para esta sessão.

minimal_address · boolean · padrão: "false"

Habilite o modo de coleta mínima de endereço. Quando habilitado, o checkout coleta apenas:

• País: Sempre necessário para determinação de impostos
• Código Postal/CEP: Apenas em regiões onde é necessário para cálculo de imposto sobre vendas, IVA ou GST

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

Habilite o endereço mínimo para a conclusão mais rápida do checkout. A coleta completa de endereço permanece disponível para empresas que exigem detalhes completos de cobrança.

UI Customization & Features

customization · object

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

Mostrar Customization object properties

theme · string · padrão: "system"

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

show_order_details · boolean · padrão: "true"

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

show_on_demand_tag · boolean · padrão: "true"

Mostrar a tag “sob demanda” para produtos aplicáveis.

force_language · string

Force a interface de checkout a renderizar em um idioma específico. Por padrão, o checkout detecta automaticamente o idioma do navegador do cliente.

Códigos de idiomas suportados: 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

feature_flags · object

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

Mostrar Feature flags object properties

allow_currency_selection · boolean · padrão: "true"

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

allow_discount_code · boolean · padrão: "true"

Mostrar campo de entrada de código de desconto na interface de checkout.

allow_phone_number_collection · boolean · padrão: "true"

Coletar números de telefone dos clientes durante o checkout.

allow_tax_id · boolean · padrão: "true"

Permitir que os clientes insiram números de identificação fiscal.

always_create_new_customer · boolean · padrão: "false"

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

allow_customer_editing_email · boolean

Permitir que os clientes editem seu endereço de email durante o checkout.

allow_customer_editing_name · boolean

Permitir que os clientes editem seu nome durante o checkout.

allow_customer_editing_street · boolean

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

allow_customer_editing_city · boolean

Permitir que os clientes editem a cidade durante o checkout.

allow_customer_editing_state · boolean

Permitir que os clientes editem o estado durante o checkout.

allow_customer_editing_country · boolean

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

allow_customer_editing_zipcode · boolean

Permitir que os clientes editem o CEP durante o checkout.

minimal_address · boolean · padrão: "false"

Habilite o modo de coleta mínima de endereço. Quando habilitado, o checkout coleta apenas:

• País: Sempre necessário para determinação de impostos
• Código Postal/CEP: Apenas em regiões onde é necessário para cálculo de imposto sobre vendas, IVA ou GST

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

Habilite o endereço mínimo para a conclusão mais rápida do checkout. A coleta completa de endereço permanece disponível para empresas que exigem detalhes completos de cobrança.

redirect_immediately · boolean · padrão: "false"

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

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

Custom Fields

custom_fields · array

Recolha informações adicionais dos clientes durante o checkout com campos de formulário personalizados. Você pode definir até 5 campos personalizados por sessão de checkout. As respostas dos clientes estão incluídas nos payloads de webhook e disponíveis via API.

Mostrar Custom field object properties

key · string · obrigatório

Identificador único para este campo. Usado como a chave nos payloads de webhook e respostas da API.

Exemplo: "company_name", "referral_source", "team_size"

label · string · obrigatório

Rótulo exibido ao cliente no formulário de checkout.

Exemplo: "Company Name", "How did you hear about us?", "Team Size"

field_type · string · obrigatório

Tipo de campo que determina as regras de validação de entrada.

Tipos disponíveis:

• text - Entrada de texto de linha única
• number - Entrada numérica
• email - Endereço de email com validação
• url - URL com validação
• date - Seletor de data
• dropdown - Selecione entre opções predefinidas
• boolean - Alternar Sim/Não

required · boolean · padrão: "false"

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

placeholder · string

Texto de espaço reservado exibido no campo de entrada.

options · array

Lista de opções para o tipo de campo dropdown. Necessário quando field_type é dropdown, ignorado para outros tipos.

Exemplo: ["Google", "Twitter", "Friend referral", "Other"]

Respostas dos clientes aos campos personalizados estã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

Subscription Configuration

subscription_data · object

Configuração adicional para sessões de checkout contendo produtos de assinatura.

Mostrar Subscription data object properties

trial_period_days · integer

Número de dias para o período de teste antes da primeira cobrança. Deve estar entre 0 e 10.000 dias.

on_demand · object

Configuração de assinatura sob demanda para faturamento baseado em uso ou medido.

Mostrar On-demand object properties

mandate_only · boolean · obrigatório

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

product_price · integer

Preço do produto para a cobrança inicial ao cliente. Se não especificado, o preço armazenado do produto será usado.

Formato: Representado na menor denominação da moeda (por exemplo, centavos para USD). Por exemplo, para cobrar $1.00, passe 100.

product_currency · string

Moeda opcional do preço do produto. Se não especificado, o padrão será a moeda do produto.

product_description · string

Descrição opcional do produto para faturamento e itens de linha. Se não especificado, a descrição armazenada do produto será usada.

adaptive_currency_fees_inclusive · boolean

Se taxas de câmbio adaptativas devem ser incluídas no preço do produto (verdadeiro) ou adicionadas por cima (falso). Ignorado se o precificação adaptativa não estiver ativado.

​

Exemplos de Uso

Aqui estão 10 exemplos abrangentes mostrando diferentes configurações de sessão de checkout para vários cenários de negócio:

​

1. Checkout Simples de Produto Único

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

​

2. Carrinho com Múltiplos Produtos

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'John Doe',
    phone_number: '[phone]'
  },
  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: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: '[e-mail]',
    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 será direcionado diretamente para a página de checkout, ignorando qualquer etapa de confirmação.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Alex Johnson',
    phone_number: '[phone]'
  },
  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 billing_currency só entra em vigor quando a moeda adaptativa está ativada nas configurações da sua conta. Se a moeda adaptativa estiver desativada, este parâmetro não terá efeito.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    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 Retornantes

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Robert Johnson',
    phone_number: '[phone]'
  },
  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: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Sarah Davis',
    phone_number: '[phone]'
  },
  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: '[e-mail]'
  }
});

​

8. Checkout com Tema Escuro e Códigos de Desconto Empilhados

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_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: '[e-mail]',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

​

9. Métodos de Pagamento Regionais (UPI para Índia)

Para informações detalhadas sobre configuração e teste de UPI, consulte a página Métodos de Pagamento na Índia.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: '[e-mail]',
    name: 'Priya Sharma',
    phone_number: '[phone]'
  },
  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 informações detalhadas sobre configuração e teste de BNPL, consulte a página Buy Now Pay Later (BNPL).

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: '[e-mail]',
    name: 'Emma Thompson',
    phone_number: '[phone]'
  },
  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. Usando Métodos de Pagamento Existentes para Checkout Instantâneo

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_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 para elegibilidade com a moeda do pagamento.

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 retornantes.

​

12. Links Curtos para URLs de Pagamento Mais Limpos

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: '[e-mail]',
    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, email ou redes sociais. São mais fáceis de lembrar e constroem mais confiança com o cliente do que URLs longas.

​

13. Pular Página de Sucesso de Pagamento com Redirecionamento Imediato

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

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

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

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

​

14. Forçando um Idioma

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

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

Use force_language quando você conhece o idioma preferido do seu cliente (por exemplo, a partir das configurações da conta) ou quando está direcionando mercados regionais específicos.

Idiomas suportados: Á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. Coletando Campos Personalizados

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_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: '[e-mail]',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

As respostas de campos personalizados são automaticamente incluídas nos payloads de webhook (payment.succeeded, subscription.active, etc.) e podem ser recuperadas via 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

​

Visualizando Sessões de Checkout

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

Node.js SDK

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

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

Python SDK

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

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

Preview API Reference

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

​

Movendo de Links Dinâmicos para Sessões de Checkout

​

Principais Diferenças

Anteriormente, ao criar um link de pagamento com Links Dinâmicos, você precisava fornecer o endereço de cobrança completo do cliente.

Com Sessões de Checkout, isso não é mais necessário. Você pode simplesmente passar as informações que possui, e nós cuidamos do resto. Por exemplo:

• Se você conhece apenas o país de cobrança do cliente, basta fornecer isso.
• O fluxo de checkout coletará automaticamente os detalhes 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, pode passar o conjunto completo de dados e incluir confirm=true no corpo da sua solicitação.

​

Processo de Migração

Migrar de Links Dinâmicos para Sessões de Checkout é simples:

1. Update your integration

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

2. Adjust request payload

   Ajuste o payload da solicitação de acordo com o formato de Sessões de Checkout.

3. That's it!

   Sim. Nenhum manuseio adicional ou passos especiais de migração são necessários do seu lado.

​

Referência de 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 de API para visualizar preços, impostos e totais antes de criar uma sessão