Crie experiências de checkout seguras e hospedadas que gerenciam todo o fluxo de pagamento para compras únicas e assinaturas com controle total de personalização.
Validade da Sessão: As sessões de checkout são válidas por 24 horas por padrão. Se você passar confirm=true em sua solicitação, a sessão será válida apenas por 15 minutos.
import DodoPayments from 'dodopayments';// Initialize the Dodo Payments clientconst 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: '[email protected]', 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 routeapp.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' }); }});
Copiar
import osfrom dodopayments import DodoPayments# Initialize the Dodo Payments clientclient = 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": "[email protected]", "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 routefrom flask import Flask, jsonify, requestapp = 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
Copiar
// Direct API call using fetch - useful for any JavaScript environmentasync 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: '[email protected]', 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 checkoutcreateCheckoutSession().then(session => { window.location.href = session.checkout_url;});
Direcione seu cliente para a URL de checkout para concluir a compra.
Copiar
// Redirect immediatelywindow.location.href = session.checkout_url;// Or open in new windowwindow.open(session.checkout_url, '_blank');
Opções de Integração Alternativas: Em vez de redirecionar, você pode incorporar o checkout diretamente em sua página usando Overlay Checkout (sobreposição modal) ou Inline Checkout (totalmente incorporado). Ambas as opções usam a mesma URL de sessão de checkout.
3
Lidar com o retorno
Após o pagamento, os clientes são redirecionados para seu return_url com parâmetros de consulta adicionais para o status do pagamento.
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 Misturado: Você pode combinar produtos de pagamento único e produtos de assinatura na mesma sessão de checkout. Isso possibilita casos de uso poderosos, como taxas de configuração com assinaturas, pacotes de hardware com SaaS e muito mais.
Valor que o cliente paga se pay_what_you_want estiver habilitado. Se desabilitado, este campo será ignorado.Formato: Representado na menor denominação da moeda (por exemplo, centavos para USD). Por exemplo, para cobrar $1,00, passe 100.
Encontre Seus IDs de Produto: Você pode encontrar os IDs dos produtos no seu painel do Dodo Payments em Produtos → Ver Detalhes, ou usando a API List Products.
Número de telefone do cliente no formato internacional. Obrigatório para alguns métodos de pagamento e prevenção de fraudes.Formato: Inclua o código do país, por exemplo, "+1234567890" para números dos EUA
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"
Código do país em duas letras (ISO 3166-1 alpha-2). Este campo é sempre obrigatório quando o endereço de cobrança é fornecido.Exemplos: "US" (Estados Unidos), "CA" (Canadá), "GB" (Reino Unido), "DE" (Alemanha)
Controle quais métodos de pagamento estão disponíveis para os clientes durante o checkout. Isso ajuda a otimizar para mercados ou requisitos de negócios específicos.Opções Disponíveis: credit, debit, upi_collect, upi_intent, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, sepa, ach, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal
Crítico: Sempre inclua credit e debit como opções de fallback para evitar falhas no checkout quando os métodos de pagamento preferidos não estão disponíveis.
Substitua a seleção de moeda padrão por uma moeda de cobrança fixa. Usa códigos de moeda ISO 4217.Moedas Suportadas: USD, EUR, GBP, CAD, AUD, INR, e maisExemplo: "USD" para Dólares Americanos, "EUR" para Euros
Este campo só é eficaz quando a precificação adaptativa está habilitada. Se a precificação adaptativa estiver desabilitada, a moeda padrão do produto será usada.
Habilite o modo de coleta de endereço mínimo. Quando habilitado, o checkout coleta apenas:
País: Sempre necessário para determinação de impostos
Código ZIP/Postal: Apenas em regiões onde é necessário para cálculo de imposto sobre vendas, VAT ou GST
Isso reduz significativamente a fricção do checkout ao eliminar campos de formulário desnecessários.
Habilite o endereço mínimo para uma conclusão de checkout mais rápida. A coleta de endereço completo permanece disponível para empresas que exigem detalhes de cobrança completos.
Habilite o modo de coleta de endereço mínimo. Quando habilitado, o checkout coleta apenas:
País: Sempre necessário para determinação de impostos
Código ZIP/Postal: Apenas em regiões onde é necessário para cálculo de imposto sobre vendas, VAT ou GST
Isso reduz significativamente a fricção do checkout ao eliminar campos de formulário desnecessários.
Habilite o endereço mínimo para uma conclusão de checkout mais rápida. A coleta de endereço completo permanece disponível para empresas que exigem detalhes de cobrança completos.
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.
Se as taxas de moeda adaptativa devem ser incluídas no preço do produto (verdadeiro) ou adicionadas em cima (falso). Ignorado se a precificação adaptativa não estiver habilitada.
A substituição billing_currency só tem efeito quando a moeda adaptativa está habilitada nas configurações da sua conta. Se a moeda adaptativa estiver desabilitada, este parâmetro não terá efeito.
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 do método de pagamento:
Copiar
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 quanto à 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 que retornam.
12. Links Curtos para URLs de Pagamento Mais Limpos
Gere links de pagamento encurtados e compartilháveis com slugs personalizados:
Copiar
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: '[email protected]', name: 'John Doe' }});// The checkout_url will be a shortened, cleaner linkconsole.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 lembrar e geram mais confiança do cliente do que URLs longas.
Use redirect_immediately: true quando você tiver uma página de sucesso personalizada que oferece uma melhor experiência do usuário do que a página de sucesso de pagamento padrão. 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, pulando completamente a página de sucesso padrão.
Anteriormente, ao criar um link de pagamento com Links Dinâmicos, você era obrigado a fornecer o endereço de cobrança completo do cliente.Com as Sessões de Checkout, isso não é mais necessário. Você pode simplesmente passar as informações que possui, e nós cuidaremos do resto. Por exemplo:
Se você só souber o país de cobrança do cliente, basta fornecer isso.
O fluxo de checkout coletará automaticamente os detalhes ausentes antes de mover o cliente para a página de pagamento.
Por outro lado, se você já tiver todas as informações necessárias e quiser pular diretamente para a página de pagamento, pode passar o conjunto completo de dados e incluir confirm=true no corpo da sua solicitação.
