Skip to main content

Prerequisites

To integrate the Dodo Payments API, you’ll need:
  • A Dodo Payments merchant account
  • API Credentials (API key and webhook secret key) from dashboard

Dashboard Setup

  1. Navigate to the Dodo Payments Dashboard
  2. Crea un prodotto (pagamento una tantum o abbonamento). I prodotti in abbonamento devono avere un prezzo di almeno $1 (o l’equivalente nella valuta scelta); gli importi inferiori a questo minimo non sono supportati.
  3. Generate your API key:
    • Go to Developer > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  4. Configure webhooks:
    • Go to Developer > Webhooks
    • Create a webhook URL for payment notifications
    • Copy the webhook secret key in env

Integration

Scegli il percorso di integrazione più adatto al tuo caso d’uso:
  • Checkout Sessions (recommended): ideale per la maggior parte delle integrazioni. Crea una sessione sul tuo server e reindirizza i clienti a un checkout sicuro e ospitato.
  • Overlay Checkout: usalo quando hai bisogno di un’esperienza all’interno della pagina che apra il checkout come overlay modale sul tuo sito.
  • Inline Checkout: incorpora il checkout direttamente nel layout della pagina per un’esperienza di checkout completamente integrata e personalizzata.
  • Static Payment Links: URL senza codice, condivisibili immediatamente, per raccogliere rapidamente i pagamenti.
  • Dynamic Payment Links: link creati programmaticamente. Tuttavia, sono consigliate le Checkout Sessions, che offrono maggiore flessibilità.
  • Mobile Checkout SDKs: per app native Android, iOS, React Native e Flutter. Crea la sessione sul tuo server come indicato sopra, quindi passa checkout_url all’SDK.
Overlay Checkout e Inline Checkout funzionano solo nel browser: incorporano il checkout in una pagina web. Se stai creando un’app mobile nativa, crea la checkout session sul tuo server e aprila con i Mobile Checkout SDKs.

1. Checkout Sessions

Usa Checkout Sessions per creare un’esperienza di checkout sicura e ospitata per pagamenti una tantum o abbonamenti. Crea una sessione sul tuo server, quindi reindirizza il cliente a checkout_url restituito.
Le checkout sessions sono valide per impostazione predefinita per 24 ore. Se passi confirm=true, le sessioni sono valide per 15 minuti e tutti i campi obbligatori devono essere forniti.
1

Create a checkout session

Scegli l’SDK che preferisci o chiama la REST API.
2

Redirect customer to checkout

Dopo la creazione della sessione, reindirizza a checkout_url per avviare il flusso ospitato.
Preferisci Checkout Sessions per il modo più rapido e affidabile di iniziare ad accettare pagamenti. Per una personalizzazione avanzata, consulta la guida completa a Checkout Sessions e il riferimento API.

2. Overlay Checkout

Per un’esperienza di checkout fluida all’interno della pagina, esplora la nostra integrazione Overlay Checkout, che consente ai clienti di completare i pagamenti senza lasciare il tuo sito.

3. Inline Checkout

Per esperienze di checkout completamente integrate e incorporate direttamente nella pagina, usa la nostra integrazione Inline Checkout. Puoi creare riepiloghi dell’ordine personalizzati e avere il pieno controllo sul layout del checkout, mentre Dodo Payments gestisce in modo sicuro la raccolta dei pagamenti. Gli static payment links ti consentono di accettare rapidamente i pagamenti condividendo un semplice URL. Puoi personalizzare l’esperienza di checkout passando query parameters per precompilare i dati del cliente, controllare i campi del modulo e aggiungere metadata personalizzati.
1

Construct your payment link

Inizia con l’URL di base e aggiungi il tuo ID prodotto:
2

Add core parameters

Includi i query parameters essenziali:
  • integer
    predefinito:"1"
    Numero di articoli da acquistare.
  • string
    obbligatorio
    URL a cui reindirizzare dopo il completamento del pagamento.
L’URL di reindirizzamento includerà i dettagli del pagamento come query parameters, ad esempio:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

Se il prodotto ha le license keys abilitate, verrà aggiunto anche un parametro license_key (separato da virgole per più chiavi):
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
3

Pre-fill customer information (optional)

Aggiungi i campi del cliente o di fatturazione come query parameters 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.
  • string
    Indirizzo.
  • string
    Città.
  • string
    Stato o provincia.
  • string
    Codice postale/CAP.
  • boolean
    true o false
4

Control form fields (optional)

Puoi disabilitare campi specifici per renderli di sola lettura per il cliente. È utile quando disponi già dei dati del cliente (ad esempio, per utenti che hanno effettuato l’accesso).
Per disabilitare un campo, fornisci il relativo valore e imposta il flag disable… corrispondente su true:
La disabilitazione dei campi aiuta a prevenire modifiche accidentali e garantisce la coerenza dei dati.
Impostando showDiscounts=false disabiliterai e nasconderai la sezione degli sconti nel modulo di checkout. Usalo se vuoi impedire ai clienti di inserire codici coupon o promozionali durante il checkout.
5

Add advanced controls (optional)

  • string
    Specifica la valuta del pagamento. Per impostazione predefinita usa la valuta del Paese di fatturazione.
  • boolean
    predefinito:"true"
    Mostra o nascondi il selettore della valuta.
  • integer
    Importo in centesimi (solo per la modalità Pay What You Want).
  • string
    Campi metadata personalizzati (ad esempio, metadata_orderId=123).
6

Share the link

Invia il payment link completato al tuo cliente. Quando lo visita, tutti i query parameters vengono raccolti e memorizzati con un ID sessione. L’URL viene quindi semplificato per includere solo il parametro della sessione (ad esempio, ?session=sess_1a2b3c4d). Le informazioni memorizzate persistono dopo i refresh della pagina e sono accessibili durante l’intero processo di checkout.
L’esperienza di checkout del cliente è ora semplificata e personalizzata in base ai tuoi parametri.
Preferisci Checkout Sessions per la maggior parte dei casi d’uso: offrono maggiore flessibilità e controllo.
Creati tramite una chiamata API o il nostro SDK con i dati del cliente. Ecco un esempio: Esistono due API per creare dynamic payment links: La guida seguente riguarda la creazione di payment link una tantum. Per istruzioni dettagliate sull’integrazione degli abbonamenti, consulta questa guida all’integrazione degli abbonamenti.
Assicurati di passare payment_link = true per ottenere il payment link
Dopo aver creato il payment link, reindirizza i tuoi clienti per completare il pagamento.

Implementazione dei Webhook

Configura un endpoint API per ricevere le notifiche dei pagamenti. Ecco un esempio con Next.js:
La nostra implementazione dei webhook segue la specifica Standard Webhooks. Per le definizioni dei tipi di webhook, consulta la nostra guida agli eventi webhook.

Eventi da ascoltare

Attiva payload.type e gestisci gli eventi pertinenti a un flusso di pagamento una tantum. Come minimo, ascolta:
Completa sempre l’ordine su payment.succeeded ricevuto dal webhook, non sul reindirizzamento del browser: il reindirizzamento potrebbe non essere eseguito se il cliente chiude la scheda, mentre il webhook viene ritentato fino alla conferma della ricezione.
Se vendi prodotti digitali con license keys, gestisci anche license_key.created. Per l’elenco completo degli eventi, inclusi gli eventi relativi ad abbonamenti, entitlement, crediti, recovery e dunning, consulta la guida agli eventi webhook. Puoi consultare questo progetto con un’implementazione demo su GitHub che utilizza Next.js e TypeScript. Puoi provare l’implementazione live qui.

Informazioni importanti su Checkout e valute

Gli importi dinamici (Pay-What-You-Want) sono espressi nella valuta di base del prodotto, non in una valuta locale arbitraria; inoltre, la valuta di base è limitata a USD, INR, GBP ed EUR. Per raccogliere un importo fisso in un’altra valuta (ad esempio PHP), non puoi passarlo direttamente: usa Adaptive Pricing (converte l’importo di base al tasso di cambio corrente) oppure Localized Pricing (prezzo fisso per valuta, ma non compatibile con Pay-What-You-Want).
Imposta esplicitamente la valuta. Passa billing_currency e billing_address.country nella checkout session. Se omessi, la valuta e il Paese vengono rilevati dall’IP del cliente (Adaptive Currency) e potrebbero non corrispondere a ciò che intendi addebitare.
Le checkout sessions scadono dopo 24 ore (15 minuti quando confirm: true) e ogni checkout_url è monouso: genera una nuova sessione per ogni cliente e per ogni tentativo di pagamento, invece di riutilizzare un link.
Acquisto ripetuto con un clic. Per un cliente di ritorno con un metodo di pagamento salvato, passa payment_method_id insieme a confirm: true per addebitare immediatamente l’importo, ignorando completamente la selezione del metodo.

Riferimento API correlato

Create Checkout Session

Riferimento API per creare checkout sessions sicure e ospitate per pagamenti una tantum e abbonamenti

Create Payment Link

Riferimento API per creare programmaticamente dynamic payment links
Ultima modifica il 31 luglio 2026