Skip to main content

Checkout Sessions

Crea un checkout sicuro e ospitato per pagamenti una tantum e abbonamenti.

Payment Links

Condividi un URL per raccogliere pagamenti senza codice.

Webhooks

Ricevi gli eventi di pagamento e completa gli ordini.

API Reference

Documentazione completa degli endpoint e test in tempo reale.

Prerequisiti

Prima di iniziare, ti servono:
  • Un account Dodo Payments.
  • Almeno un prodotto. Crealo nella sezione Products della dashboard. Un prodotto in abbonamento con un prezzo diverso da zero deve rispettare il minimo per gli abbonamenti per la valuta utilizzata dal cliente: $1.00 per USD. Le valute diverse da USD, EUR e GBP devono inoltre avere un valore di almeno $1.00. Sono supportati anche gli abbonamenti da $0.
  • Una chiave API. Creala nella sezione Developer → API Keys e salvala nella variabile d’ambiente DODO_PAYMENTS_API_KEY. Crea la chiave in modalità test durante lo sviluppo: gli esempi in questa pagina usano la modalità test e una chiave in modalità test funziona solo con la modalità test. Consulta Authentication.
  • L’SDK per il tuo linguaggio. L’SDK Node.js richiede Node.js 20 o versioni successive, l’SDK Python richiede Python 3.9 o versioni successive e l’SDK Go richiede Go 1.22 o versioni successive. Gli esempi cURL non richiedono alcun SDK.
Anche l’esempio di webhook usa il pacchetto standardwebhooks. Installalo con npm install standardwebhooks.

Scegli un percorso di integrazione

Il checkout in overlay e quello inline funzionano solo in una pagina web. In un’app mobile nativa, crea la sessione Checkout sul tuo server e apri il relativo checkout_url con un SDK Checkout per dispositivi mobili. Per fare in modo che un coding agent crei questa integrazione per te, installa il Plugin per agent.

Sessioni Checkout

Crea un’esperienza di checkout sicura e ospitata. Crea una sessione sul tuo server, quindi reindirizza il cliente all’checkout_url restituito.
Ogni checkout_url funziona una sola volta e scade dopo 24 ore, oppure dopo 15 minuti quando passi confirm: true. Con confirm: true devi inoltre fornire ogni campo obbligatorio. Crea una nuova sessione per ogni cliente e per ogni tentativo di pagamento.

Crea una sessione Checkout

Reindirizza al Checkout

Dopo aver creato una sessione, reindirizza il cliente all’checkout_url:
Per una personalizzazione avanzata, consulta la guida completa sulle Sessioni Checkout e l’API Reference.

Gestisci gli errori

Quando una richiesta non va a buon fine, l’API restituisce un codice di stato HTTP e un corpo JSON con un code e un message. Basa la gestione degli errori su code, non su message. Per ogni codice, la relativa causa e come risolverlo, consulta Codici di errore. Un pagamento non riuscito viene segnalato separatamente: il relativo status è failed, il relativo error_code indica il motivo e ricevi un payment.failed webhook. Per decidere se riprovare, consulta Gestisci i pagamenti non riusciti. Un link di pagamento è un URL che apre il checkout per un prodotto, così puoi riscuotere pagamenti senza scrivere codice. I parametri di query precompilano i dati del cliente e controllano il modulo di checkout. Quando un cliente apre il link, il checkout salva i parametri in una sessione e accorcia l’URL in un parametro session, così vengono mantenuti anche dopo un aggiornamento della pagina. Un link di pagamento statico è un URL che crei una volta e condividi più volte. L’URL di base è:
Aggiungi parametri di query per personalizzare il checkout:
integer
predefinito:"1"
Numero di articoli da acquistare.
string
obbligatorio
I link di pagamento usano redirect_url. L’API Checkout Sessions usa return_url allo stesso scopo.URL a cui reindirizzare dopo il pagamento. Dodo Payments aggiunge i dettagli del pagamento come parametri di query, ad esempio https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Se il prodotto emette chiavi di licenza, viene aggiunto anche un parametro license_key, con più chiavi separate da virgole.
string
Specifica la valuta del pagamento. Per impostazione predefinita usa la valuta del paese di fatturazione.
boolean
predefinito:"true"
Mostra o nasconde il selettore della valuta.
boolean
predefinito:"true"
Mostra o nasconde la sezione degli sconti. Imposta su false per impedire ai clienti di inserire codici coupon.
number
Fissa l’importo addebitato, nelle unità principali della valuta, ad esempio 12.5 per $12.50. Funziona solo con i prodotti Pay What You Want e viene ignorato se è inferiore al prezzo minimo del prodotto.
paymentAmount usa le unità principali della valuta (12.5 corrisponde a $12.50). Il campo dell’API Checkout Sessions product_cart[].amount usa l’unità più piccola della valuta (1250 corrisponde a $12.50). Consulta Prezzi dinamici.
string
Campi di metadati personalizzati, ad esempio metadata_orderId=123.

Precompila le informazioni del cliente

Aggiungi i campi del cliente come parametri di query per velocizzare il checkout:
string
Nome completo del cliente (ignorato se vengono forniti firstName o lastName).
string
Nome del cliente.
string
Cognome del cliente.
string
Indirizzo email del cliente.
string
Paese del cliente (codice ISO 3166-1 alpha-2).
string
Indirizzo.
string
Città.
string
Stato o provincia.
string
Codice postale o ZIP.

Disabilita i campi del modulo

Per impedire ai clienti di modificare le informazioni precompilate, disabilita un campo fornendo il relativo valore e impostando il flag disable... corrispondente su true:
La disabilitazione dei campi impedisce modifiche accidentali e garantisce la coerenza dei dati.
Gli endpoint POST /payments e POST /subscriptions sono deprecati. Per le nuove integrazioni usa invece le Sessioni Checkout.
Per le integrazioni esistenti che usano link di pagamento dinamici, passa payment_link: true a Crea pagamento una tantum o Crea abbonamento per creare un link. Gli esempi seguenti creano un link di pagamento una tantum. Per gli abbonamenti, consulta la Guida all’integrazione degli abbonamenti.

Webhook

I webhook informano il tuo server quando un pagamento va a buon fine o non va a buon fine, così puoi evadere l’ordine.

Crea un endpoint webhook

Vai a Developer → Webhooks nella dashboard e aggiungi l’URL del tuo endpoint. Copia il secret di firma dell’endpoint nella variabile d’ambiente DODO_PAYMENTS_WEBHOOK_KEY. Ecco un esempio con Next.js:
app/api/webhooks/dodo/route.ts
La nostra implementazione dei webhook segue la specifica Standard Webhooks.

Eventi da ascoltare

Come minimo, ascolta questi eventi in un flusso di pagamento una tantum:
Evadi sempre l’ordine su payment.succeeded ricevuto dal webhook, non sul reindirizzamento del browser. Il reindirizzamento può non verificarsi se il cliente chiude la scheda, mentre il webhook viene ritentato fino alla ricezione di una conferma.
Se vendi prodotti con chiavi di licenza, gestisci anche license_key.created. Per l’elenco completo degli eventi, inclusi quelli relativi ad abbonamenti, entitlement, crediti, recupero e solleciti di pagamento, consulta la Guida agli eventi webhook. Per un esempio completo con Next.js e TypeScript, consulta il repository demo e il relativo deployment live.

Valuta e indirizzo di fatturazione

Per addebitare una valuta specifica, passa billing_currency e billing_address.country quando crei la sessione Checkout. Se li ometti, Adaptive Currency sceglie la valuta e il paese dall’indirizzo IP del cliente, che potrebbe non corrispondere alla valuta che intendi addebitare. Gli importi Pay What You Want sono espressi nella valuta di base del prodotto, che deve essere USD, GBP o EUR. Per riscuotere un importo fisso in un’altra valuta, usa Adaptive Currency, che converte il prezzo di base ai tassi di cambio correnti, oppure Prezzi localizzati, che imposta un prezzo fisso per valuta. I Prezzi localizzati non funzionano con Pay What You Want.

Acquisto ripetuto con un clic

Per addebitare un cliente di ritorno con un metodo di pagamento salvato, passa il relativo payment_method_id insieme a confirm: true. payment_method_id è accettato solo quando confirm è true e devi inoltre passare l’customer_id del cliente esistente. Poiché confirm è true, devi passare anche un billing_address completo oppure solo country e zipcode quando minimal_address è true. La sessione addebita direttamente il metodo di pagamento salvato, quindi non restituisce alcun checkout_url. Usa i webhook per sapere se il pagamento è andato a buon fine.

Pagine correlate

Checkout Sessions

Guida completa con opzioni di personalizzazione avanzate.

Overlay Checkout

Incorpora il checkout come overlay modale nella tua pagina.

Inline Checkout

Incorpora il checkout direttamente nel layout della tua pagina.

Subscription Integration

Configura la fatturazione ricorrente.

Webhook Event Guide

Elenco completo di tutti gli eventi webhook.

API Reference

Documentazione dell’API Checkout Sessions.
Ultima modifica il 8 ottobre 2026