Skip to main content

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.
Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

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

API Response

All methods return:
Only 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:
Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

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 con un prodotto in abbonamento nella stessa sessione. Un carrello può contenere anche due o più prodotti in abbonamento, ma in questo caso non può contenere prodotti con pagamento una tantum. Consulta Carrello con più abbonamenti. Un carrello può contenere al massimo 20 prodotti.
Trova gli ID dei prodotti: puoi trovare gli ID dei prodotti nel dashboard di Dodo Payments in Products → View Details, oppure usando la List Products API.

Campi facoltativi

object
Informazioni sul cliente. Puoi associare un cliente esistente usando il suo ID oppure creare un nuovo record cliente durante il checkout.
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, a meno che minimal_address non sia true.
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.
Includi sempre credit e debit come opzioni di fallback per evitare errori di checkout quando i metodi di pagamento preferiti non sono disponibili.
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, l’API ignora questo campo e la valuta viene ricavata dal prezzo del prodotto o dal paese di fatturazione.
boolean
predefinito:"false"
Mostra i metodi di pagamento salvati in precedenza ai clienti di ritorno, migliorando la velocità del checkout e l’esperienza utente.
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 (solo country e zipcode quando minimal_address è true)
  • payment_method_id può essere fornito per elaborare immediatamente l’addebito
  • La sessione scade dopo 15 minuti invece di 24 ore
  • È richiesto un customer_id esistente se viene fornito payment_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
Questo riduce significativamente gli attriti durante il checkout eliminando i campi del modulo non necessari.Con confirm: true, è richiesto solo zipcode (oltre a country); gli altri campi dell’indirizzo di fatturazione rimangono facoltativi.
string
Un metodo di pagamento salvato appartenente al cliente associato. Richiede confirm: true e un customer.customer_id esistente. L’idoneità del metodo di pagamento viene convalidata rispetto alla valuta del pagamento. Quando viene impostato, l’addebito viene elaborato immediatamente e checkout_url viene restituito come null. Usa invece payment_id restituito.
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 Raccolte di prodotti.
string
Codice fiscale del cliente (ad esempio, un numero IVA). Richiede billing_address con un country.
string
Nome commerciale o legale facoltativo associato al codice 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 processor è max(this_floor, actual_billing_amount), quindi questo rappresenta di fatto il limite di autorizzazione mostrato al cliente ogni volta che la fatturazione è inferiore. Se non impostato, viene applicata la configurazione del merchant; se anche questa non è impostata, viene applicato il valore predefinito di sistema di ₹15,000.
object
Personalizza l’aspetto e il comportamento dell’interfaccia di checkout.
object
Configura funzionalità e comportamenti specifici per la sessione di checkout.
array
Raccogli informazioni aggiuntive dai clienti durante il checkout tramite 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.
Le risposte dei clienti ai campi personalizzati sono incluse in:
  • Webhook: payment.succeeded, subscription.active e altri payload di eventi pertinenti contengono l’array custom_field_responses
  • Risposte dell’API: gli oggetti di pagamento e abbonamento includono custom_field_responses
object
Configurazione aggiuntiva per le sessioni di checkout che contengono prodotti in abbonamento.

Esempi di utilizzo

Checkout semplice per un singolo prodotto

Carrello con più prodotti

Carrello con più abbonamenti

Per vendere diversi prodotti in abbonamento in un unico checkout, aggiungi due o più prodotti in abbonamento a product_cart. Il cliente paga una sola volta e Dodo Payments crea un pagamento, una fattura e un abbonamento per ogni prodotto. Ogni abbonamento ha il proprio ciclo di fatturazione e si rinnova autonomamente, quindi un prodotto mensile e uno annuale possono condividere lo stesso carrello.
Un carrello con più abbonamenti ha questi limiti:
  • Non può contenere prodotti con pagamento una tantum. L’API rifiuta la richiesta con un 422.
  • Può contenere al massimo 20 prodotti in abbonamento.
  • Non può elencare due volte lo stesso prodotto. Per vendere più di un’unità di un prodotto, imposta invece quantity.
  • Non può utilizzare la fatturazione on-demand (subscription_data.on_demand).
  • Un codice sconto applicato al carrello conta come una redemption.
subscription_data.trial_period_days si applica a ogni abbonamento nel carrello. In sua assenza, ogni abbonamento utilizza la prova impostata sul proprio prodotto. Se non lo imposti e Prevent Trial Misuse è attivo, un prodotto per il quale il cliente ha già usufruito di una prova inizia senza periodo di prova. Il pagamento risultante ha is_multi_subscription: true ed elenca ogni abbonamento avviato in subscription_ids. Il suo subscription_id è null, perché nessun singolo abbonamento è proprietario del pagamento. Il webhook payment.succeeded contiene gli stessi campi. Leggi is_multi_subscription per trovare il tipo di pagamento, non la lunghezza di subscription_ids. Dopo il completamento del pagamento, ricevi un evento payment.succeeded per il carrello e un evento subscription.active per ogni abbonamento. Da quel momento, ogni abbonamento si rinnova, cambia piano e viene annullato autonomamente, con una fattura separata per ogni rinnovo. Tutti gli abbonamenti dello stesso carrello condividono il metodo di pagamento utilizzato dal cliente durante il checkout. Quando aggiorni il metodo di pagamento di uno di essi, Dodo Payments trasferisce il nuovo metodo di pagamento a ogni abbonamento dello stesso carrello che abbia la stessa valuta di regolamento e la stessa valuta di fatturazione e sia active, on_hold, past_due o paused. Ogni abbonamento di un carrello inizia con la stessa valuta di regolamento e la stessa valuta di fatturazione, anche quando i prodotti hanno valute di prezzo diverse. Una modifica successiva, come un cambio di piano, può spostare un abbonamento a un’altra valuta di regolamento o di fatturazione. Tale abbonamento mantiene il vecchio metodo di pagamento, quindi aggiornalo separatamente. Per un abbonamento on_hold, l’aggiornamento ritenta solo la fattura non pagata di quell’abbonamento.

Abbonamento con periodo di prova

Checkout preconfermato

Checkout con sostituzione della valuta

Metodi di pagamento salvati per i clienti di ritorno

Checkout B2B con raccolta del Tax ID

Checkout con tema scuro e codici sconto impilati

Metodi di pagamento regionali (UPI per l’India)

Per informazioni dettagliate sulla configurazione e sui test di UPI, consulta la pagina Metodi di pagamento per l’India.

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 metodo di pagamento esistente

Ignorare la pagina di conferma del pagamento con reindirizzamento immediato

Forzare una lingua

Raccolta di campi personalizzati

Anteprima delle sessioni di checkout

Usa l’endpoint Anteprima della sessione di checkout per calcolare prezzi, imposte e totali prima di creare una sessione. È utile per visualizzare informazioni precise sui prezzi nel tuo sito.
L’current_breakup.subtotal visualizzato in anteprima riflette già la Parità del potere d’acquisto e il Charm Pricing quando applicabili al prodotto.
Quando il carrello contiene un prodotto in abbonamento, la risposta di 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 una prova, altrimenti now + one payment frequency. Il campo viene omesso per i carrelli composti solo da prodotti 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 della prova, gratuita o a pagamento) e trial_amount (il costo della prova per unità dopo gli sconti, nelle unità minime della valuta del prezzo). trial_amount è presente solo per una prova a pagamento ed è null per una prova gratuita o in assenza di prova. Usa current_breakup per il totale tassato effettivamente dovuto oggi.
Per un carrello con più abbonamenti, la risposta restituisce anche un array subscriptions con una voce per ogni abbonamento: product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days e next_billing_date. L’next_billing_date di primo livello è la data più vicina nel carrello, mentre trial_period_days e trial_amount di primo livello sono null. Leggi gli importi da subscriptions e current_breakup. recurring_breakup somma gli importi di rinnovo di ogni abbonamento, anche quando si rinnovano in date diverse, quindi leggi ogni rinnovo da subscriptions.
Se utilizzi Dynamic Links, Checkout Sessions offre maggiore flessibilità. Con Dynamic Links dovevi fornire l’indirizzo di fatturazione completo del cliente. Con Checkout Sessions puoi passare 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 dati rimanenti.
  • Oppure fornisci tutte le informazioni e imposta confirm: true per passare direttamente alla pagina di pagamento.
La migrazione è semplice: aggiorna la tua integrazione per utilizzare l’API Checkout Sessions o il metodo SDK, modifica il payload della richiesta in modo che corrisponda al formato Checkout Sessions e il gioco è fatto. Non è necessaria alcuna gestione aggiuntiva.

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
Ultima modifica il 8 ottobre 2026