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 avere un prezzo di almeno $1 o l’equivalente nella relativa valuta. Sono supportati anche gli abbonamenti da $0.
  • Una chiave API. Creala in 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.

Scegli un percorso di integrazione

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

Checkout Sessions

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 o 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 di checkout

Reindirizza al checkout

Dopo aver creato una sessione, reindirizza il cliente all’checkout_url:
Per una personalizzazione avanzata, consulta la guida completa Checkout Sessions e l’API Reference.
Un link di pagamento è un URL che apre il checkout per un prodotto, permettendoti di raccogliere 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 a un parametro session, in modo che vengano 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 per lo 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 equivale a $12.50). Il campo product_cart[].amount dell’API Checkout Sessions usa l’unità minima della valuta (1250 equivale a $12.50). Consulta Dynamic Pricing.
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 semplificare 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 Checkout Sessions.
Per le integrazioni esistenti che usano link di pagamento dinamici, passa payment_link: true a Create One-Time Payment o Create Subscription per creare un link. Gli esempi seguenti creano un link di pagamento una tantum. Per gli abbonamenti, consulta la Subscription Integration Guide.

Webhook

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

Crea un endpoint webhook

Vai a Developer → Webhooks nella dashboard e aggiungi l’URL del tuo endpoint. Copia il signing secret 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:
Completa 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 conferma della ricezione.
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 Webhook Event Guide. 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 di checkout. Se li ometti, Adaptive Currency sceglie valuta e paese dall’indirizzo IP del cliente, che potrebbe non corrispondere alla valuta in cui intendi addebitare il pagamento. 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 Localized Pricing, che imposta un prezzo fisso per valuta. Localized Pricing non funziona con Pay What You Want.

Acquisto ripetuto con un clic

Per addebitare un cliente esistente usando 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 anche passare customer_id del cliente esistente. Poiché confirm è true, devi passare anche un billing_address completo. 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 26 settembre 2026