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 e prodotti con abbonamento nella stessa sessione.
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.
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, 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.
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_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 l’attrito nel checkout eliminando i campi del modulo non necessari.
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.
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.
object
Personalizza l’aspetto e il comportamento dell’interfaccia di checkout.
object
Configura funzioni e comportamenti specifici per la sessione di checkout.
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.
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 API: gli oggetti di pagamento e abbonamento includono custom_field_responses
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

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.
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: true per passare direttamente alla pagina di pagamento.
La migrazione è semplice: aggiorna l’integrazione per usare l’API Checkout Sessions o il relativo metodo SDK, modifica il payload della richiesta affinché 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 28 settembre 2026