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
- Navigate to the Dodo Payments Dashboard
- 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.
-
Generate your API key:
- Go to Developer > API
- Detailed Guide
- Copy the API key the in env named DODO_PAYMENTS_API_KEY
-
Configure webhooks:
- Go to Developer > Webhooks
- Create a webhook URL for payment notifications
- Copy the webhook secret key in env
Integration
Payment Links
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_urlall’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 acheckout_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.
- Node.js SDK
- Python SDK
- REST API
2
Redirect customer to checkout
Dopo la creazione della sessione, reindirizza a
checkout_url per avviare il flusso ospitato.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.4. Static Payment Links
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:
-
integerpredefinito:"1"Numero di articoli da acquistare.
-
stringobbligatorioURL a cui reindirizzare dopo il completamento del pagamento.
L’URL di reindirizzamento includerà i dettagli del pagamento come query parameters, ad esempio:
Se il prodotto ha le license keys abilitate, verrà aggiunto anche un parametro
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.comSe 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.com3
Pre-fill customer information (optional)
Aggiungi i campi del cliente o di fatturazione come query parameters per semplificare il checkout.
Supported Customer Fields
Supported Customer Fields
-
stringNome completo del cliente (ignorato se vengono forniti firstName o lastName).
-
stringNome del cliente.
-
stringCognome del cliente.
-
stringIndirizzo email del cliente.
-
stringPaese del cliente.
-
stringIndirizzo.
-
stringCittà.
-
stringStato o provincia.
-
stringCodice postale/CAP.
-
booleantrue 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).
disable… corrispondente su true:- Disable Flags Table
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)
-
stringSpecifica la valuta del pagamento. Per impostazione predefinita usa la valuta del Paese di fatturazione.
-
booleanpredefinito:"true"Mostra o nascondi il selettore della valuta.
-
integerImporto in centesimi (solo per la modalità Pay What You Want).
-
stringCampi 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.
4. Dynamic Payment Links
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:- One-time Payment Link API riferimento API
- Subscription Payment Link API riferimento API
Assicurati di passare
payment_link = true per ottenere il payment link - Node.js SDK
- Python SDK
- Go SDK
- Api Reference
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:Eventi da ascoltare
Attivapayload.type e gestisci gli eventi pertinenti a un flusso di pagamento una tantum. Come minimo, ascolta:
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
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