Quick Start
Create your first checkout session in under 5 minutes
API Reference
Full API documentation and interactive testing
Preview Endpoint
Calculate pricing and taxes before creating a session
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when
confirm: true.Prerequisites
You need:- An active Dodo Payments merchant account
- API credentials from Developer → API Keys in the dashboard
- At least one product created in Products
Creating Your First Checkout Session
- Node.js SDK
- Python SDK
- REST API
API Response
All methods return:session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead.
When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.
Redirect Your Customer
1
Extract the checkout URL
Get
checkout_url from the API response.2
Redirect to checkout
Send your customer to the URL:Alternatively, open in a new window:
3
Handle the return
After payment, customers are redirected to your
return_url with query parameters:Example redirect:
Controllare lo stato della sessione
Per controllare lo stato di una sessione, chiama Get Checkout Session (GET /checkouts/{id}). La risposta contiene id, created_at, customer_email e customer_name della sessione, oltre a payment_id e payment_status. Entrambi i campi di pagamento hanno valore null mentre il cliente sta ancora inserendo i dati. Dopo che il cliente invia il pagamento, payment_status contiene lo stato del pagamento, ad esempio succeeded, failed o processing. Usa i webhook come fonte autorevole per l’evasione.
Corpo della richiesta
Campi obbligatori
array
obbligatorio
Array di prodotti da includere nella sessione di checkout. Ogni prodotto deve avere un
product_id valido dal tuo dashboard.Puoi combinare prodotti con pagamento una tantum e prodotti con abbonamento nella stessa sessione.Campi facoltativi
Customer Information
Customer Information
object
Informazioni sul cliente. Puoi associare un cliente esistente usando il suo ID oppure creare un nuovo record cliente durante il checkout.
- Attach Existing Customer
- Create New Customer
object
Informazioni sull’indirizzo di fatturazione per un calcolo accurato delle imposte, la prevenzione delle frodi e la conformità normativa.Quando
confirm: true, tutti i campi dell’indirizzo di fatturazione diventano obbligatori.Payment Configuration
Payment Configuration
array
Controlla quali metodi di pagamento sono disponibili ai clienti durante il checkout. Questo aiuta a ottimizzare il checkout per mercati o requisiti aziendali specifici.Opzioni comuni:
credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalConsulta il riferimento della Create Checkout Session API per l’elenco completo.Esempio:string
Sostituisci la selezione predefinita della valuta con una valuta di fatturazione fissa. Usa i codici valuta ISO 4217.Valute supportate:
USD, EUR, GBP, CAD, AUD, INR e altreEsempio: "USD" per i dollari statunitensi, "EUR" per gli euroQuesto campo è efficace solo quando il pricing adattivo è abilitato. Se il pricing adattivo è disabilitato, viene usata la valuta predefinita del prodotto.boolean
predefinito:"false"
Mostra i metodi di pagamento salvati in precedenza ai clienti di ritorno, migliorando la velocità del checkout e l’esperienza utente.
Session Management
Session Management
string
URL a cui reindirizzare i clienti dopo il completamento del pagamento. Dodo Payments aggiunge parametri di query al tuo URL durante il reindirizzamento (vedi la tabella dei reindirizzamenti sopra).URL di reindirizzamento di esempio:Usa i parametri di query
license_key e email per mostrare le chiavi di licenza o inviare immediatamente una conferma nella pagina di ritorno, senza richiedere una chiamata API aggiuntiva.string
URL a cui reindirizzare i clienti quando fanno clic sul pulsante Indietro o annullano la sessione di checkout. Se non viene fornito, il pulsante Indietro non viene visualizzato.Imposta un
cancel_url per offrire ai clienti un modo chiaro per tornare al tuo sito senza completare l’acquisto.boolean
predefinito:"false"
Se true, finalizza immediatamente tutti i dettagli della sessione. L’API genera un errore se mancano dati obbligatori.Quando
confirm: true:- Tutti i campi dell’indirizzo di fatturazione diventano obbligatori
payment_method_idpuò essere fornito per elaborare immediatamente l’addebito- La sessione scade dopo 15 minuti invece di 24 ore
- È richiesto un
customer_idesistente se viene fornitopayment_method_id
array
Applica uno o più codici sconto cumulativi alla sessione di checkout. I codici vengono applicati nell’ordine dell’array (il primo codice riduce il prezzo iniziale, il secondo riduce il prezzo già scontato e così via), fino a un massimo di 20 codici per sessione.Quando è abilitata la Purchasing Power Parity, il prezzo iniziale è l’importo modificato dalla PPP, non il prezzo base.Il singolo campo
discount_code riportato di seguito è deprecato, ma ancora pienamente supportato. Non può essere combinato con discount_codes nella stessa richiesta.string
deprecato
Deprecato — per le nuove integrazioni, preferisci
discount_codes. Questo campo continua a funzionare per la compatibilità con le versioni precedenti, ma non può essere combinato con discount_codes nella stessa richiesta.object
Coppie chiave-valore personalizzate per memorizzare informazioni aggiuntive sulla sessione.
boolean
Sostituisci il comportamento 3DS predefinito del merchant per questa sessione.
boolean
predefinito:"false"
Abilita la modalità di raccolta minima dell’indirizzo. Quando è abilitata, il checkout raccoglie solo:
- Paese: sempre obbligatorio per la determinazione delle imposte
- ZIP/Codice postale: solo nelle regioni in cui è necessario per il calcolo di sales tax, VAT o GST
string
Metodo di pagamento salvato appartenente al cliente associato. Richiede
confirm: true e un customer.customer_id esistente. Il metodo di pagamento viene convalidato per verificarne l’idoneità rispetto alla valuta del pagamento. Quando impostato, l’addebito viene elaborato immediatamente e checkout_url viene restituito come null. Usa invece payment_id restituito.boolean
predefinito:"false"
Se true, restituisce un URL di checkout abbreviato invece dell’URL completo della sessione.
string
ID della raccolta di prodotti per il flusso di checkout basato sulle raccolte. Quando lo imposti, passa un array
product_cart vuoto. I codici sconto non possono essere applicati in anticipo durante la creazione della sessione. Consulta Product Collections.string
ID fiscale del cliente (ad esempio, un numero VAT). Richiede
billing_address con un country.string
Nome commerciale o legale facoltativo associato all’ID fiscale, fino a 250 caratteri. Se fornito insieme a un
tax_id valido, viene visualizzato sulla fattura al posto del nome personale del cliente.integer
Sostituisci il limite minimo del mandato a livello di merchant (in paise INR) per gli e-mandate INR sulle carte indiane.L’importo del mandato inviato al processore è
max(this_floor, actual_billing_amount), quindi questo rappresenta di fatto il limite massimo di autorizzazione visibile al cliente quando la fatturazione è inferiore. Se non impostato, viene applicata l’impostazione del merchant; se anche quella non è impostata, viene applicato il valore predefinito del sistema di ₹15,000.UI Customization
UI Customization
object
Personalizza l’aspetto e il comportamento dell’interfaccia di checkout.
Feature Flags
Feature Flags
object
Configura funzioni e comportamenti specifici per la sessione di checkout.
Custom Fields
Custom Fields
array
Raccogli informazioni aggiuntive dai clienti durante il checkout con campi 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.
- Webhook:
payment.succeeded,subscription.activee altri payload di eventi pertinenti contengono l’arraycustom_field_responses - Risposte API: gli oggetti di pagamento e abbonamento includono
custom_field_responses
Subscription Configuration
Subscription Configuration
object
Configurazione aggiuntiva per le sessioni di checkout che contengono prodotti con abbonamento.
Esempi di utilizzo
Checkout semplice per un singolo prodotto
Carrello con più prodotti
Abbonamento con periodo di prova
Checkout preconfermato
Checkout con override della valuta
Metodi di pagamento salvati per i clienti di ritorno
Checkout B2B con raccolta dell’ID fiscale
Checkout con tema scuro e codici sconto cumulativi
Metodi di pagamento regionali (UPI per l’India)
Per informazioni dettagliate sulla configurazione e sui test di UPI, consulta la pagina India Payment Methods.Checkout BNPL (Buy Now Pay Later)
Per informazioni dettagliate sulla configurazione e sui test di BNPL, consulta la pagina Buy Now Pay Later (BNPL).Checkout istantaneo con un metodo di pagamento esistente
Link brevi per URL di pagamento più ordinati
Ignorare la pagina di esito positivo del pagamento con reindirizzamento immediato
Forzare una lingua
Raccogliere campi personalizzati
Visualizzare in anteprima le sessioni di checkout
Usa l’endpoint Preview Checkout Session per calcolare prezzi, imposte e totali prima di creare una sessione. È utile per mostrare informazioni accurate sui prezzi nel tuo sito.L’
current_breakup.subtotal visualizzato in anteprima riflette già Purchasing Power Parity e Charm Pricing quando applicabili al prodotto.Quando il carrello contiene un prodotto con abbonamento, la risposta dell’anteprima restituisce anche un
next_billing_date: un’anteprima della prossima data di fatturazione, che puoi mostrare prima della creazione dell’abbonamento. Viene calcolato rispetto al momento attuale: now + trial period quando si applica un periodo di prova, altrimenti now + one payment frequency. Il campo viene omesso per i carrelli composti solo da acquisti una tantum. Si tratta di una stima ancorata al momento dell’anteprima; l’next_billing_date autorevole viene impostato quando l’abbonamento si attiva.L’anteprima restituisce anche
trial_period_days (la durata effettiva del periodo di prova, gratuito o a pagamento) e trial_amount (il costo della prova per unità dopo gli sconti, nelle unità minori della valuta del prezzo). trial_amount è presente solo per una paid trial ed è null per una prova gratuita o in assenza di prova. Usa current_breakup per il totale tassato effettivamente dovuto oggi.- Node.js SDK
- Python SDK
- REST API
Migrazione da Dynamic Links
Se usi Dynamic Links, Checkout Sessions offre maggiore flessibilità. Con Dynamic Links dovevi fornire l’indirizzo di fatturazione completo del cliente. Con Checkout Sessions puoi trasmettere le informazioni disponibili e il flusso di checkout raccoglie il resto. Ad esempio:- Fornisci solo il paese di fatturazione del cliente e il checkout raccoglie i dettagli rimanenti.
- Oppure fornisci tutte le informazioni e imposta
confirm: trueper passare direttamente alla pagina di pagamento.
Risorse correlate
Overlay Checkout
Apri il checkout come overlay modale nella tua pagina
Inline Checkout
Incorpora il checkout direttamente nella tua pagina
Mobile Integration
Integra il checkout nelle app mobili native
Webhooks
Ascolta gli eventi di pagamento e abbonamento
Payment Methods
Metodi di pagamento supportati per regione
Subscriptions
Fatturazione ricorrente e gestione degli abbonamenti