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 · obbligatorio

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.

Mostra Product Cart Item Properties

product_id · string · obbligatorio

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

Example: "prod_123abc456def"

quantity · integer · obbligatorio

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.

Mostra Addon item properties

addon_id · string · obbligatorio

quantity · integer · obbligatorio

amount · integer

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

Formato: Rappresentato nella minima denominazione della valuta (ad esempio, centesimi per il USD). Per esempio, per addebitare $1.00, passa 100.

credit_entitlements · array

Sovrascrittura per sessione di pagamento per i crediti già associati a questo prodotto. Usalo per concedere un numero diverso di crediti per questa singola sessione — ad esempio, un pacchetto promozionale che concede 1.000 crediti API invece dei 500 predefiniti del prodotto — senza creare un prodotto separato.

Ogni credit_entitlement_id deve essere già collegato al prodotto. Questo campo sovrascrive solo il credits_amount concesso quando questa sessione è completata; le impostazioni di assegnazione del credito a livello di prodotto (scadenza, trasferimento, ecc.) si applicano ancora.

Mostra Credit entitlement override properties

credit_entitlement_id · string · obbligatorio

ID dell’assegnazione del credito da sovrascrivere. Deve essere già collegato al prodotto.

credits_amount · string · obbligatorio

Numero di crediti da concedere per questa sessione di pagamento, sovrascrivendo il credits_amount a livello di prodotto. Deve essere maggiore di zero.

Trova i tuoi ID prodotto: Puoi trovare gli ID prodotto nella tua dashboard Dodo Payments sotto Prodotti → Visualizza dettagli, oppure utilizzando l’API Elenco prodotti.

​

Campi opzionali

Configura questi campi per personalizzare l’esperienza di pagamento e aggiungere logica aziendale al tuo flusso di pagamenti.

Customer Information

customer · object

Informazioni sul cliente. Puoi allegare un cliente esistente utilizzando il loro ID o creare un nuovo record cliente durante il checkout.

Attach Existing Customer

Collega un cliente esistente alla sessione di pagamento utilizzando il loro ID.

Mostra Existing Customer Properties

customer_id · string · obbligatorio

L’identificatore univoco di un cliente esistente. Usa questo per collegare la sessione di pagamento a un cliente esistente invece di crearne uno nuovo.

New Customer

Crea un nuovo record cliente durante il checkout.

Mostra New Customer Properties

email · string · obbligatorio

Indirizzo email del cliente. Necessario quando si crea un nuovo cliente.

name · string

Nome completo del cliente come dovrebbe apparire su ricevute e fatture.

Esempio: "John Doe" o "Jane Smith"

phone_number · string

Numero di telefono del cliente in formato internazionale. Necessario per alcuni metodi di pagamento e per la prevenzione delle frodi.

Formato: Includi il prefisso internazionale, ad esempio, "[phone]" per i numeri statunitensi

billing_address · object

Informazioni sull’indirizzo di fatturazione per un calcolo preciso delle tasse, la prevenzione delle frodi e la conformità normativa.

Quando confirm è impostato su true, tutti i campi dell’indirizzo di fatturazione diventano obbligatori per la creazione con successo della sessione.

Mostra Billing address object properties

street · string

Completa l’indirizzo stradale includendo il numero civico, il nome della strada e il numero dell’appartamento/unità se applicabile.

Esempio: "123 Main St, Apt 4B" o "456 Oak Avenue"

city · string

Nome della città o del comune.

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

state · string

Nome dello stato, provincia o regione. Usa nomi completi o abbreviazioni standard.

Esempio: "California" o "CA", "Ontario" o "ON"

country · string · obbligatorio

Codice ISO del paese a due lettere (ISO 3166-1 alpha-2). Questo campo è sempre richiesto quando viene fornito l’indirizzo di fatturazione.

Esempi: "US" (Stati Uniti), "CA" (Canada), "GB" (Regno Unito), "DE" (Germania)

Country Code Reference

Visualizza l’elenco completo dei paesi supportati e dei loro codici ISO

zipcode · string

Codice postale, ZIP code o equivalente in base ai requisiti del paese.

Esempi: "94102" (US), "M5V 3A8" (Canada), "SW1A 1AA" (UK)

Payment Configuration

allowed_payment_method_types · array

Controlla quali metodi di pagamento sono disponibili per i clienti durante il checkout. Questo aiuta a ottimizzare per mercati specifici o requisiti aziendali.

Opzioni Disponibili: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal, sunbit

Critico: Includere sempre credit e debit come opzioni di ripiego per prevenire errori di pagamento quando i metodi di pagamento preferiti non sono disponibili.

Esempio:

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

billing_currency · string

Sovrascrive la selezione della valuta predefinita con una valuta di fatturazione fissa. Usa i codici valuta ISO 4217.

Valute supportate: USD, EUR, GBP, CAD, AUD, INR, e altro

Esempio: "USD" per Dollari Statunitensi, "EUR" per Euro

Questo campo è efficace solo quando il prezzo adattivo è abilitato. Se il prezzo adattivo è disabilitato, verrà utilizzata la valuta predefinita del prodotto.

show_saved_payment_methods · boolean · predefinito: "false"

Visualizza metodi di pagamento salvati in precedenza per i clienti che ritornano, migliorando la velocità del checkout e l’esperienza utente.

Session Management

return_url · string

URL per reindirizzare i clienti dopo il completamento del pagamento. Dodo Payments aggiunge i seguenti parametri di query al tuo URL al momento del reindirizzamento:

Parametro	Tipo	Condizione
payment_id	string	Sempre presente per pagamenti una tantum
subscription_id	string	Sempre presente per i pagamenti con abbonamento
status	string	Sempre presente
license_key	string	Presente se il prodotto ha chiavi di licenza abilitate. Separati da virgola se ce ne sono molteplici
email	string	Presente se il cliente ha un’email registrata

Esempi di URL di reindirizzamento:

# 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

Usa i parametri di query license_key e email per visualizzare immediatamente le chiavi di licenza o inviare una conferma sulla tua pagina di ritorno, senza bisogno di una chiamata API extra.

cancel_url · string

URL a cui reindirizzare i clienti quando cliccano il pulsante di ritorno o annullano la sessione di pagamento. Se non fornito, il pulsante di ritorno non verrà visualizzato.

Imposta un cancel_url per offrire ai clienti un modo chiaro di tornare al tuo sito senza completare l’acquisto. Questo migliora l’esperienza di checkout e riduce le frizioni.

confirm · boolean · predefinito: "false"

Se vero, finalizza immediatamente tutti i dettagli della sessione. L’API genererà un errore se i dati richiesti mancano.

discount_codes · array

Applica uno o più codici sconto impilabili alla sessione di checkout. I codici vengono applicati nell’ordine dell’array (il primo codice riduce il prezzo base, il secondo riduce il prezzo già scontato, e così via), fino a un massimo di 20 codici per sessione.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

Il campo singolare discount_code qui sotto è deprecato ma ancora pienamente supportato — le integrazioni esistenti continuano a funzionare senza modifiche. Non può essere combinato con discount_codes nella stessa richiesta. Passa a discount_codes quando conveniente per sfruttare l’impilamento.

discount_code · string · deprecato

Deprecato — preferisci discount_codes per nuove integrazioni. Questo campo funziona ancora per compatibilità con versioni precedenti, ma non può essere combinato con discount_codes nella stessa richiesta.

metadata · object

Coppie chiave-valore personalizzate per memorizzare informazioni aggiuntive sulla sessione.

force_3ds · boolean

Sovrascrivi il comportamento predefinito del 3DS del commerciante per questa sessione.

minimal_address · boolean · predefinito: "false"

Abilita la modalità di raccolta indirizzo minima. Quando abilitata, il checkout raccoglie solo:

• Paese: Sempre richiesto per la determinazione delle tasse
• CAP/Codice postale: Solo nelle regioni dove è necessario per il calcolo dell’IVA o la determinazione delle tasse di vendita

Questo riduce significativamente la frizione durante il checkout eliminando campi del modulo non necessari.

Abilita la modalità di indirizzo minimo per una conclusione del checkout più veloce. La raccolta completa dell’indirizzo rimane disponibile per le aziende che richiedono dettagli completi di fatturazione.

UI Customization & Features

customization · object

Personalizza l’aspetto e il comportamento dell’interfaccia di checkout.

Mostra Customization object properties

theme · string · predefinito: "system"

Tema per l’interfaccia di checkout. Opzioni: light, dark, o system.

show_order_details · boolean · predefinito: "true"

Mostra la sezione dei dettagli dell’ordine nell’interfaccia di checkout.

show_on_demand_tag · boolean · predefinito: "true"

Mostra l’etichetta “on-demand” per i prodotti applicabili.

force_language · string

Forza l’interfaccia di checkout a essere visualizzata in una lingua specifica. Per impostazione predefinita, il checkout rileva automaticamente la lingua del browser del cliente.

Codici lingua supportati: ar (Arabo), ca (Catalano), de (Tedesco), en (Inglese), es (Spagnolo), fr (Francese), he (Ebraico), id (Indonesiano), it (Italiano), ja (Giapponese), ko (Coreano), ms (Malese), nl (Olandese), pl (Polacco), pt (Portoghese), ro (Rumeno), ru (Russo), sv (Svedese), th (Tailandese), tr (Turco), zh (Cinese)

Esempio: "es" per Spagnolo, "ja" per Giapponese

feature_flags · object

Configura caratteristiche e comportamenti specifici per la sessione di checkout.

Mostra Feature flags object properties

allow_currency_selection · boolean · predefinito: "true"

Permetti ai clienti di selezionare la loro valuta preferita durante il checkout.

allow_discount_code · boolean · predefinito: "true"

Mostra il campo di inserimento del codice sconto nell’interfaccia di checkout.

allow_phone_number_collection · boolean · predefinito: "true"

Raccogli numeri di telefono dei clienti durante il checkout.

allow_tax_id · boolean · predefinito: "true"

Permetti ai clienti di inserire numeri di identificazione fiscale.

always_create_new_customer · boolean · predefinito: "false"

Forza la creazione di un nuovo record cliente invece di aggiornare quelli esistenti.

allow_customer_editing_email · boolean

Permetti ai clienti di modificare il loro indirizzo email durante il checkout.

allow_customer_editing_name · boolean

Permetti ai clienti di modificare il proprio nome durante il checkout.

allow_customer_editing_street · boolean

Permetti ai clienti di modificare l’indirizzo stradale durante il checkout.

allow_customer_editing_city · boolean

Permetti ai clienti di modificare la città durante il checkout.

allow_customer_editing_state · boolean

Permetti ai clienti di modificare lo stato durante il checkout.

allow_customer_editing_country · boolean

Permetti ai clienti di modificare il paese durante il checkout.

allow_customer_editing_zipcode · boolean

Permetti ai clienti di modificare il codice postale durante il checkout.

minimal_address · boolean · predefinito: "false"

Abilita la modalità di raccolta indirizzo minima. Quando abilitata, il checkout raccoglie solo:

• Paese: Sempre richiesto per la determinazione delle tasse
• CAP/Codice postale: Solo nelle regioni dove è necessario per il calcolo dell’IVA o la determinazione delle tasse di vendita

Questo riduce significativamente la frizione durante il checkout eliminando campi del modulo non necessari.

Abilita la modalità di indirizzo minimo per una conclusione del checkout più veloce. La raccolta completa dell’indirizzo rimane disponibile per le aziende che richiedono dettagli completi di fatturazione.

redirect_immediately · boolean · predefinito: "false"

Salta la pagina di successo del pagamento predefinita e reindirizza immediatamente i clienti al tuo return_url dopo il completamento del pagamento.

Usa questo quando hai una pagina di successo personalizzata che offre una migliore esperienza utente, o per app mobili e flussi di checkout incorporati.

Custom Fields

custom_fields · array

Raccogli informazioni aggiuntive dai clienti durante il checkout con campi del modulo personalizzati. Puoi definire fino a 5 campi personalizzati per sessione di checkout. Le risposte dei clienti sono incluse nei payload dei webhook e disponibili tramite l’API.

Mostra Custom field object properties

key · string · obbligatorio

Identificatore univoco per questo campo. Utilizzato come chiave nei payload dei webhook e nelle risposte API.

Esempio: "company_name", "referral_source", "team_size"

label · string · obbligatorio

Etichetta visualizzata mostrata al cliente nel modulo di checkout.

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

field_type · string · obbligatorio

Tipo di campo che determina le regole di convalida degli input.

Tipi disponibili:

• text - Input di testo a singola riga
• number - Input numerico
• email - Indirizzo email con convalida
• url - URL con convalida
• date - Selettore di data
• dropdown - Selezione da opzioni predefinite
• boolean - Interruttore Sì/No

required · boolean · predefinito: "false"

Se questo campo deve essere compilato prima che il checkout possa essere completato.

placeholder · string

Testo del segnaposto visualizzato nel campo di input.

options · array

Elenco delle opzioni per il tipo di campo dropdown. Richiesto quando field_type è dropdown, ignorato per gli altri tipi.

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

Le risposte dei clienti ai campi personalizzati sono incluse in:

• Webhooks: payment.succeeded, subscription.active e altri payload di eventi rilevanti contengono l’array custom_field_responses
• Risposte API: Gli oggetti di pagamento e sottoscrizione includono custom_field_responses

Subscription Configuration

subscription_data · object

Configurazione aggiuntiva per le sessioni di checkout contenenti prodotti in abbonamento.

Mostra Subscription data object properties

trial_period_days · integer

Numero di giorni per il periodo di prova prima del primo addebito. Deve essere tra 0 e 10000 giorni.

on_demand · object

Configurazione per abbonamenti su richiesta con fatturazione basata sull’uso o misurata.

Mostra On-demand object properties

mandate_only · boolean · obbligatorio

Se impostato su vero, non esegue alcun addebito e autorizza solo i dettagli del metodo di pagamento per l’uso futuro.

product_price · integer

Prezzo del prodotto per l’addebito iniziale al cliente. Se non specificato, verrà utilizzato il prezzo memorizzato del prodotto.

Formato: Rappresentato nella minima denominazione della valuta (ad esempio, centesimi per il USD). Per esempio, per addebitare $1.00, passa 100.

product_currency · string

Valuta opzionale del prezzo del prodotto. Se non specificato, predefinito alla valuta del prodotto.

product_description · string

Descrizione opzionale del prodotto per la fatturazione e le voci di linea. Se non specificato, verrà utilizzata la descrizione memorizzata del prodotto.

adaptive_currency_fees_inclusive · boolean

Se le commissioni di conversione valuta adattive devono essere incluse nel prezzo del prodotto (vero) o aggiunte sopra (falso). Ignorato se il prezzo adattivo non è abilitato.

​

Esempi di utilizzo

Ecco 10 esempi completi che mostrano diverse configurazioni della sessione di checkout per vari scenari aziendali:

​

1. Checkout di un singolo prodotto semplice

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. Carrello multi-prodotto

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. Abbonamento con periodo di prova

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 preconfermato

Quando confirm è impostato su true, il cliente verrà portato direttamente alla pagina di checkout, saltando eventuali passaggi di conferma.

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 con sovrascrittura valuta

La sovrascrittura billing_currency ha effetto solo quando la valuta adattiva è abilitata nelle impostazioni del tuo account. Se la valuta adattiva è disabilitata, questo parametro non avrà effetto.

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. Metodi di pagamento salvati per i clienti di ritorno

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 con raccolta ID fiscale

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 a tema scuro con codici sconto impilati

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. Metodi di pagamento regionali (UPI per l’India)

Per informazioni dettagliate sulla configurazione e il test UPI, vedere la pagina Metodi di pagamento India.

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)

Per informazioni dettagliate sulla configurazione e il test BNPL, vedere la pagina 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. Utilizzo di metodi di pagamento esistenti per checkout immediato

Usa un metodo di pagamento salvato dal cliente per creare una sessione di checkout che si processa immediatamente, saltando la raccolta del metodo di 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'
});

Quando si utilizza payment_method_id, confirm deve essere impostato su true e deve essere fornito un customer_id esistente. Il metodo di pagamento verrà convalidato per l’idoneità con la valuta del pagamento.

Il metodo di pagamento deve appartenere al cliente ed essere compatibile con la valuta del pagamento. Questo abilita acquisti in un clic per i clienti di ritorno.

​

12. Link brevi per URL di pagamento più puliti

Genera link di pagamento abbreviati e condivisibili con slug personalizzati:

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

I link brevi sono perfetti per SMS, e-mail o condivisione sui social media. Sono più facili da ricordare e costruiscono maggiore fiducia nei clienti rispetto a URL lunghi.

​

13. Salta pagina di successo del pagamento con reindirizzamento immediato

Reindirizza immediatamente i clienti dopo il completamento del pagamento, bypassando la pagina di successo predefinita:

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'
  }
});

Usa redirect_immediately: true quando hai una pagina di successo personalizzata che fornisce un’esperienza utente migliore rispetto alla pagina di successo del pagamento predefinita. Questo è particolarmente utile per app mobili e flussi di checkout incorporati.

Quando redirect_immediately è abilitato, i clienti vengono reindirizzati al vostro return_url immediatamente dopo il completamento del pagamento, saltando completamente la pagina di successo predefinita.

​

14. Forzare una lingua

Forza il checkout a essere visualizzato in una lingua specifica, sovrascrivendo il rilevamento della lingua del browser del 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'
});

Usa force_language quando conosci la lingua preferita del tuo cliente (ad es., dalle impostazioni del loro account) o quando stai puntando a mercati regionali specifici.

Lingue supportate: Arabo (ar), Catalano (ca), Cinese (zh), Olandese (nl), Inglese (en), Francese (fr), Tedesco (de), Ebraico (he), Indonesiano (id), Italiano (it), Giapponese (ja), Coreano (ko), Malese (ms), Polacco (pl), Portoghese (pt), Rumeno (ro), Russo (ru), Spagnolo (es), Svedese (sv), Tailandese (th), Turco (tr)

​

15. Raccolta di campi personalizzati

Raccogli informazioni aggiuntive dai clienti durante il checkout utilizzando campi personalizzati:

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'
});

Le risposte ai campi personalizzati sono automaticamente incluse nei payload dei webhook (payment.succeeded, subscription.active, ecc.) e possono essere recuperate tramite l’API. Usale per arricchire il tuo CRM, attivare flussi di onboarding o personalizzare l’esperienza del cliente.

Tipi di campo disponibili: text, number, email, url, date, dropdown, boolean

​

Anteprima delle sessioni di checkout

Prima di creare una sessione di checkout, puoi visualizzare in anteprima la ripartizione dei prezzi inclusi tasse, sconti e totali. Questo è utile per visualizzare prezzi accurati ai clienti prima che procedano al 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

Visualizza la documentazione completa dell’endpoint di anteprima.

​

Passare da Link Dinamici a Sessioni di Checkout

​

Differenze principali

In precedenza, quando si creava un link di pagamento con Link Dinamici, era necessario fornire l’indirizzo di fatturazione completo del cliente.

Con le Sessioni di Checkout, questo non è più necessario. Puoi semplicemente passare le informazioni che hai, e ci occuperemo del resto. Per esempio:

• Se conosci solo il paese di fatturazione del cliente, basta fornire quello.
• Il flusso di pagamento raccoglierà automaticamente i dettagli mancanti prima di spostare il cliente alla pagina di pagamento.
• D’altra parte, se hai già tutte le informazioni richieste e vuoi passare direttamente alla pagina di pagamento, puoi passare il set completo di dati e includere confirm=true nel corpo della tua richiesta.

​

Processo di migrazione

La migrazione da Link Dinamici a Sessioni di Checkout è semplice:

1. Update your integration

   Aggiorna la tua integrazione per utilizzare il nuovo metodo API o SDK.

2. Adjust request payload

   Regola il payload della richiesta secondo il formato delle Sessioni di Checkout.

3. That's it!

   Sì. Non sono necessarie ulteriori gestioni o passaggi di migrazione speciali dalla tua parte.

​

Riferimento API correlato

Create Checkout Session

Riferimento API completo per la creazione di sessioni di checkout con tutti i parametri e le opzioni disponibili

Preview Checkout Session

Riferimento API per visualizzare in anteprima i prezzi, le tasse e i totali prima di creare una sessione