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, viene utilizzata la valuta del paese di fatturazione.
  • boolean
    predefinito:"true"
    Mostra o nasconde il selettore della valuta.
  • number
    Imposta l’importo addebitato, espresso nelle unità principali della valuta (ad es. 12.5 per 12,50 $). Solo per i prodotti Pay What You Want. Il valore viene ignorato se è inferiore al prezzo minimo del prodotto.
  • string
    Campi di metadati personalizzati (ad es. metadata_orderId=123).
paymentAmount in un payment link non corrisponde alla stessa unità del campo amount nell’API Checkout Sessions. Il parametro del link utilizza le unità principali della valuta (12.5 = 12,50 ),mentreproductcart[].amountdellAPIutilizzaladenominazioneminima(1250=12,50), mentre `product_cart[].amount` dell'API utilizza la denominazione minima (`1250` = 12,50 ). Consulta Dynamic Pricing per il campo dell’API.
6

Share the link

Invia il payment link completato al cliente. Quando lo visita, tutti i parametri della query vengono raccolti e memorizzati con un ID di sessione. L’URL viene quindi semplificato includendo solo il parametro della sessione (ad es. ?session=sess_1a2b3c4d). Le informazioni memorizzate persistono dopo gli aggiornamenti della pagina e sono accessibili durante tutto il 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 dettagli del cliente. Ecco un esempio: Esistono due API per creare payment link dinamici:
Entrambi gli endpoint per la creazione dei link sono deprecati. POST /payments e POST /subscriptions continuano a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliato utilizzare Checkout Sessions (POST /checkouts).
La guida seguente illustra la creazione di un payment link per pagamenti 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 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 dal webhook**, non sul reindirizzamento del browser: il reindirizzamento potrebbe non essere rilevato se il cliente chiude la scheda, mentre il webhook viene ritentato fino alla conferma della ricezione.
Se vendi prodotti digitali con chiavi di licenza, gestisci anche license_key.created. Per l’elenco completo degli eventi — inclusi gli eventi relativi ad abbonamenti, entitlement, crediti, recupero e solleciti di pagamento — consulta la Guida agli eventi webhook. Puoi consultare questo progetto con un’implementazione dimostrativa su GitHub utilizzando Next.js e TypeScript. Puoi provare l’implementazione attiva qui.

Aspetti principali da conoscere 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 riscuotere un importo fisso in un’altra valuta (ad es. PHP), non puoi passarlo direttamente: utilizza Adaptive Pricing (converte l’importo di base al tasso di cambio in tempo reale) 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 sessione di checkout. Se omessi, la valuta e il paese vengono rilevati dall’indirizzo IP del cliente (Adaptive Currency) e potrebbero non corrispondere a quelli che intendi addebitare.
Le sessioni di checkout 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 istantaneamente l’importo, ignorando completamente la selezione del metodo.

Riferimenti API correlati

Create Checkout Session

Riferimento API per la creazione di sessioni di checkout sicure e ospitate per pagamenti una tantum e abbonamenti

Create Payment Link

Riferimento API per la creazione programmatica di payment link dinamici
Ultima modifica il 6 agosto 2026