Panoramica
Il checkout inline ti consente di creare esperienze di checkout completamente integrate che si fondono perfettamente con il tuo sito web o applicazione. A differenza del checkout overlay, che si apre come un modale sopra la tua pagina, il checkout inline incorpora il modulo di pagamento direttamente nel layout della tua pagina. Utilizzando il checkout inline, puoi:- Creare esperienze di checkout completamente integrate con la tua app o sito web
- Consentire a Dodo Payments di catturare in modo sicuro le informazioni sui clienti e sui pagamenti in un frame di checkout ottimizzato
- Visualizzare articoli, totali e altre informazioni da Dodo Payments sulla tua pagina
- Utilizzare metodi e eventi SDK per costruire esperienze di checkout avanzate

Come Funziona
Il checkout inline funziona incorporando un frame sicuro di Dodo Payments nel tuo sito web o app. Il frame di checkout gestisce la raccolta delle informazioni sui clienti e la cattura dei dettagli di pagamento. La tua pagina visualizza l’elenco degli articoli, i totali e le opzioni per modificare ciò che è presente nel checkout. L’SDK consente alla tua pagina e al frame di checkout di interagire tra loro. Dodo Payments crea automaticamente un abbonamento quando un checkout viene completato, pronto per essere attivato da te.Il frame del checkout inline gestisce in modo sicuro tutte le informazioni di pagamento sensibili, garantendo la conformità PCI senza certificazioni aggiuntive da parte tua.
Cosa Rende un Buon Checkout Inline?
È importante che i clienti sappiano da chi stanno acquistando, cosa stanno acquistando e quanto stanno pagando. Per costruire un checkout inline che sia conforme e ottimizzato per la conversione, la tua implementazione deve includere:
- Informazioni ricorrenti: Se ricorrente, con quale frequenza si ripete e il totale da pagare al rinnovo. Se è una prova, quanto dura la prova.
- Descrizioni degli articoli: Una descrizione di ciò che viene acquistato.
- Totali delle transazioni: Totali delle transazioni, inclusi subtotale, totale delle tasse e totale generale. Assicurati di includere anche la valuta.
- Footer di Dodo Payments: L’intero frame di checkout inline, incluso il footer del checkout che contiene informazioni su Dodo Payments, i nostri termini di vendita e la nostra politica sulla privacy.
- Politica di rimborso: Un link alla tua politica di rimborso, se differente dalla politica standard di rimborso di Dodo Payments.
Percorso del Cliente
Il flusso di checkout è determinato dalla configurazione della tua sessione di checkout. A seconda di come configuri la sessione di checkout, i clienti vivranno un checkout che può presentare tutte le informazioni su una singola pagina o attraverso più passaggi.Customer opens checkout
Puoi aprire il checkout inline passando articoli o una transazione esistente. Usa l’SDK per mostrare e aggiornare le informazioni sulla pagina, e i metodi dell’SDK per aggiornare gli articoli in base all’interazione del cliente.

Customer enters their details
Il checkout inline chiede prima ai clienti di inserire il proprio indirizzo email, selezionare il proprio paese e (dove richiesto) inserire il proprio codice postale. Questo passaggio raccoglie tutte le informazioni necessarie per determinare le tasse e le opzioni di pagamento disponibili.Puoi precompilare i dettagli del cliente e presentare indirizzi salvati per semplificare l’esperienza.
Customer selects payment method
Dopo aver inserito i propri dettagli, ai clienti vengono presentati i metodi di pagamento disponibili e il modulo di pagamento. Le opzioni possono includere carta di credito o debito, PayPal, Apple Pay, Google Pay e altri metodi di pagamento locali in base alla loro posizione.Visualizza i metodi di pagamento salvati se disponibili per accelerare il checkout.

Checkout completed
Dodo Payments instrada ogni pagamento al miglior acquirente per quella vendita per ottenere la migliore possibilità di successo. I clienti entrano in un flusso di successo che puoi costruire.

Inizio Veloce
Inizia con il Checkout Inline di Dodo Payments in poche righe di codice:Guida all’Integrazione Passo-Passo
Initialize the SDK for Inline Display
Inizializza l’SDK e specifica
displayType: 'inline'. Dovresti anche ascoltare l’evento checkout.breakdown per aggiornare la tua UI con i calcoli in tempo reale di tasse e totali.Create a Container Element
Aggiungi un elemento al tuo HTML dove il frame del checkout sarà iniettato:
Open the Checkout
Richiama
DodoPayments.Checkout.open() con checkoutUrl e elementId del tuo contenitore:Test Your Integration
- Avvia il tuo server di sviluppo:
- Testa il flusso di checkout:
- Inserisci i tuoi dettagli email e indirizzo nel frame inline.
- Verifica che il tuo riepilogo ordine personalizzato si aggiorni in tempo reale.
- Testa il flusso di pagamento utilizzando credenziali di test.
- Conferma che i reindirizzamenti funzionino correttamente.
Dovresti vedere eventi
checkout.breakdown registrati nella console del browser se hai aggiunto un console log nel callback onEvent.Esempio Completo in React
Questo esempio dimostra come implementare un riepilogo ordini personalizzato accanto al checkout inline, mantenendoli sincronizzati tramite l’eventocheckout.breakdown.
Riferimento API
Configurazione
Opzioni di Inizializzazione
| Opzione | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
mode | "test" | "live" | Sì | Modalità dell’ambiente. |
displayType | "inline" | "overlay" | Sì | Deve essere impostato su "inline" per incorporare il checkout. |
onEvent | function | Sì | Funzione di callback per gestire gli eventi di checkout. |
Opzioni di Checkout
| Option | Type | Required | Description |
|---|---|---|---|
checkoutUrl | string | Yes | Checkout session URL. |
elementId | string | Yes | The id of the DOM element where the checkout should be rendered. |
options.showTimer | boolean | No | Show or hide the checkout timer. Defaults to true. When disabled, you will receive the checkout.link_expired event when the session expires. |
options.showSecurityBadge | boolean | No | Show or hide the security badge. Defaults to true. |
options.manualRedirect | boolean | No | When enabled, the checkout will not automatically redirect after completion. Instead, you will receive checkout.status and checkout.redirect_requested events to handle the redirect yourself. |
options.payButtonText | string | No | Custom text to display on the pay button. |
options.fontSize | FontSize | No | Global font size for the checkout. |
options.fontWeight | FontWeight | No | Global font weight for the checkout. |
Metodi
Apri Checkout
Apre il frame di checkout nel contenitore specificato.manualRedirect, gestisci il completamento del checkout nel tuo callback onEvent:
Chiudi Checkout
Rimuove programmaticamente il frame di checkout e pulisce i listener degli eventi.Controlla Stato
Restituisce se il frame di checkout è attualmente iniettato.Eventi
L’SDK fornisce eventi in tempo reale tramite il callbackonEvent. Per il checkout inline, checkout.breakdown è particolarmente utile per sincronizzare la tua UI.
| Tipo di evento | Descrizione |
|---|---|
checkout.opened | Il frame del checkout è stato caricato. |
checkout.form_ready | Il modulo di checkout è pronto per ricevere input dell’utente. Utile per nascondere gli stati di caricamento e mostrare l’interfaccia del checkout. |
checkout.breakdown | Generato quando prezzi, tasse o sconti vengono aggiornati. |
checkout.customer_details_submitted | I dati del cliente sono stati inviati. |
checkout.pay_button_clicked | Generato quando il cliente clicca il pulsante di pagamento. Utile per analisi e tracciamento dei funnel di conversione. |
checkout.redirect | Il checkout effettuerà un redirect (ad esempio verso una pagina bancaria). |
checkout.error | Si è verificato un errore durante il checkout. |
checkout.link_expired | Generato quando la sessione di checkout scade. Ricevuto solo quando showTimer è impostato su false. |
checkout.status | Generato quando manualRedirect è abilitato. Contiene lo stato del checkout (succeeded, failed o processing). |
checkout.redirect_requested | Generato quando manualRedirect è abilitato. Contiene l’URL verso cui reindirizzare il cliente. |
Dati di Breakdown del Checkout
L’eventocheckout.breakdown fornisce i seguenti dati:
Dati dell’Evento di Stato del Checkout
QuandomanualRedirect è abilitato, ricevi l’evento checkout.status con i seguenti dati:
Dati dell’Evento di Reindirizzamento del Checkout Richiesto
QuandomanualRedirect è abilitato, ricevi l’evento checkout.redirect_requested con i seguenti dati:
Comprendere l’Evento di Breakdown
L’eventocheckout.breakdown è il metodo principale per mantenere sincronizzata l’interfaccia della tua applicazione con lo stato del checkout Dodo Payments.
Quando si attiva:
- All’inizializzazione: Immediatamente dopo che il frame di checkout è stato caricato e pronto.
- Al cambio di indirizzo: Ogni volta che il cliente seleziona un paese o inserisce un codice postale che comporta un ricalcolo delle tasse.
| Campo | Descrizione |
|---|---|
subTotal | La somma di tutti gli articoli nella sessione prima che vengano applicati sconti o tasse. |
discount | Il valore totale di tutti gli sconti applicati. |
tax | L’importo delle tasse calcolate. In modalità inline, questo valore si aggiorna dinamicamente mentre l’utente interagisce con i campi dell’indirizzo. |
total | Il risultato matematico di subTotal - discount + tax nella valuta base della sessione. |
currency | Il codice valuta ISO (ad esempio "USD") per i valori standard di subtotale, sconto e tasse. |
finalTotal | L’importo effettivamente addebitato al cliente. Può includere rettifiche di cambio valuta o commissioni dei metodi di pagamento locali che non fanno parte della suddivisione base dei prezzi. |
finalTotalCurrency | La valuta in cui il cliente sta realmente pagando. Può differire da currency se è attiva la parità del potere d’acquisto o la conversione in valuta locale. |
- Formattazione della valuta: i prezzi vengono sempre restituiti come interi nell’unità monetaria più piccola (ad esempio centesimi per USD, yen per JPY). Per visualizzarli, dividili per 100 (o la potenza di 10 appropriata) oppure usa una libreria di formattazione come
Intl.NumberFormat. - Gestione degli stati iniziali: quando il checkout viene caricato per la prima volta,
taxediscountpossono essere0onullfinché l’utente non fornisce le informazioni di fatturazione o non applica un codice. La tua UI dovrebbe gestire questi stati in modo elegante (ad esempio mostrandone un trattino—o nascondendo la riga). - “Totale finale” vs “Totale”: mentre
totalti fornisce il calcolo standard del prezzo,finalTotalè la fonte di verità per la transazione. SefinalTotalè presente, riflette esattamente ciò che verrà addebitato sulla carta del cliente, incluse eventuali rettifiche dinamiche. - Feedback in tempo reale: usa il campo
taxper mostrare agli utenti che le tasse vengono calcolate in tempo reale. Ciò conferisce una sensazione “live” alla tua pagina di checkout e riduce l’attrito durante la compilazione dell’indirizzo.
Opzioni di Implementazione
Installazione tramite Package Manager
Installa tramite npm, yarn o pnpm come mostrato nella Guida all’Integrazione Passo-Passo.Implementazione CDN
Per un’integrazione rapida senza un passaggio di build, puoi utilizzare il nostro CDN:Aggiorna metodo di pagamento
L’inline checkout supporta l’aggiornamento del metodo di pagamento per le sottoscrizioni. Quando un cliente deve aggiornare il metodo di pagamento — sia per una sottoscrizione attiva sia per riattivare una sottoscrizione in sospeso — puoi rendere disponibile il flusso di aggiornamento direttamente nella struttura della tua pagina.Come funziona
- Chiama l’Update Payment Method API per ottenere un
payment_link:
- Passa il
payment_linkrestituito comecheckoutUrlper aprire l’inline checkout:
Per le sottoscrizioni in sospeso
Quando aggiorni il metodo di pagamento per una sottoscrizione in statoon_hold, Dodo Payments crea automaticamente un addebito per eventuali importi residui. Monitora i webhook payment.succeeded e subscription.active per confermare la riattivazione.
Gestione degli errori
L’SDK fornisce informazioni dettagliate sugli errori tramite il sistema di eventi. Implementa sempre una gestione adeguata degli errori nel tuo callbackonEvent:
Best Practice
- Design responsivo: Assicurati che l’elemento contenitore abbia larghezza e altezza sufficienti. L’iframe si espanderà tipicamente per riempire il contenitore.
- Sincronizzazione: Usa l’evento
checkout.breakdownper mantenere il tuo riepilogo dell’ordine o le tabelle dei prezzi personalizzati sincronizzati con ciò che l’utente vede nel frame del checkout. - Stati scheletro: Mostra un indicatore di caricamento nel contenitore finché non viene attivato l’evento
checkout.opened. - Pulizia: Chiama
DodoPayments.Checkout.close()quando il tuo componente viene smontato per rimuovere l’iframe e i listener degli eventi.
Per implementazioni in modalità scura, si consiglia di usare
#0d0d0d come colore di sfondo per un’integrazione visiva ottimale con il frame dell’inline checkout.Validazione dello stato di pagamento
Perché la validazione lato server è essenziale
Sebbene eventi dell’inline checkout comecheckout.status forniscano feedback in tempo reale, non dovrebbero essere la tua unica fonte di verità per lo stato di pagamento. Problemi di rete, crash del browser o utenti che chiudono la pagina possono far perdere eventi. Per garantire una validazione affidabile del pagamento:
- Il tuo server dovrebbe ascoltare gli eventi webhook - Dodo Payments invia webhook per i cambiamenti di stato dei pagamenti
- Implementa un meccanismo di polling - Il tuo frontend dovrebbe interrogare il server per aggiornamenti di stato
- Combina entrambi gli approcci - Usa i webhook come fonte principale e il polling come fallback
Architettura consigliata
Passaggi di implementazione
1. Ascolta gli eventi del checkout - Quando l’utente clicca su paga, inizia a prepararti per verificare lo stato:payment.succeeded o payment.failed. Consulta la nostra documentazione sui webhook per i dettagli.
Gestione dei redirect (3DS, Google Pay, UPI)
Quando si usamanualRedirect: true, alcuni metodi di pagamento richiedono di reindirizzare l’utente fuori dalla tua pagina per l’autenticazione:
- 3D Secure (3DS) - Autenticazione della carta
- Google Pay - Autenticazione del portafoglio in alcuni flussi
- UPI - Metodi di pagamento indiani con redirect
checkout.redirect_requested. Reindirizza l’utente all’URL fornito:
- Verifica se l’utente sta tornando da un redirect (ad es. tramite
sessionStorage) - Inizia a interrogare il tuo server per lo stato di pagamento confermato
- Mostra uno stato “Verifica pagamento…” durante il polling
- Visualizza l’interfaccia di successo/fallimento in base allo stato confermato dal server
Risoluzione dei problemi
Checkout frame is not appearing
Checkout frame is not appearing
- Verifica che
elementIdcorrisponda aiddi undivche esiste effettivamente nel DOM. - Assicurati che
displayType: 'inline'sia stato passato aInitialize. - Controlla che
checkoutUrlsia valido.
Taxes are not updating in my UI
Taxes are not updating in my UI
- Assicurati di ascoltare l’evento
checkout.breakdown. - Le tasse vengono calcolate solo dopo che l’utente inserisce un paese e un codice postale validi nel frame del checkout.
Abilitare i portafogli digitali
Per informazioni dettagliate su come configurare Apple Pay, Google Pay e altri portafogli digitali, consulta la pagina Portafogli digitali.Configurazione rapida per Apple Pay
Download domain association file
Scarica il file di associazione del dominio Apple Pay.
Request activation
Invia un’e-mail a support@dodopayments.com con l’URL del tuo dominio di produzione e richiedi l’attivazione di Apple Pay.
Compatibilità dei browser
L’SDK Dodo Payments Checkout supporta i seguenti browser:- Chrome (ultima versione)
- Firefox (ultima versione)
- Safari (ultima versione)
- Edge (ultima versione)
- IE11+
Inline vs Overlay Checkout
Scegli il tipo di checkout giusto per il tuo caso d’uso:| Feature | Inline Checkout | Overlay Checkout |
|---|---|---|
| Integration depth | Fully embedded in page | Modal on top of page |
| Layout control | Full control | Limited |
| Branding | Seamless | Separate from page |
| Implementation effort | Higher | Lower |
| Best for | Custom checkout pages, high-conversion flows | Quick integration, existing pages |
Risorse correlate
Overlay Checkout
Usa l’overlay checkout per un’integrazione rapida basata su modali.
Checkout Sessions API
Crea sessioni di checkout per alimentare le tue esperienze di pagamento.
Webhooks
Gestisci eventi di pagamento lato server con i webhook.
Integration Guide
Guida completa all’integrazione di Dodo Payments.
