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.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:
Example inline checkout layout showing required elements
- 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

Customer enters their details
Customer selects payment method

Checkout completed

Dodo Payments creates subscription

Inizio Veloce
Inizia con il Checkout Inline di Dodo Payments in poche righe di codice:Guida all’Integrazione Passo-Passo
Install the SDK
Initialize the SDK for Inline Display
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
Open the Checkout
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.
checkout.breakdown registrati nella console del browser se hai aggiunto un console log nel callback onEvent.Go Live
- Cambia la modalità in
'live':
- Aggiorna i tuoi URL di checkout per utilizzare sessioni di checkout live dal tuo backend.
- Testa il flusso completo in produzione.
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
Opzioni di Checkout
Metodi
Apri Checkout
Apre il frame di checkout nel contenitore specificato.Chiudi Checkout
Rimuove programmaticamente il frame del checkout e pulisce i listener di eventi.Verifica Stato
Restituisce se il frame del checkout è attualmente caricato.Eventi
L’SDK fornisce eventi in tempo reale tramite il callbackonEvent. Per il checkout inline, checkout.breakdown è particolarmente utile per sincronizzare la tua UI.
Dati Breakdown del Checkout
L’eventocheckout.breakdown fornisce i seguenti dati:
Comprensione dell’Evento Breakdown
L’eventocheckout.breakdown è il modo principale per mantenere l’interfaccia utente della tua applicazione sincronizzata con lo stato del checkout di Dodo Payments.
Quando si attiva:
- All’inizializzazione: Immediatamente dopo che il frame del checkout è stato caricato e pronto.
- Al cambio di indirizzo: Ogni volta che il cliente seleziona un paese o inserisce un codice postale che richiede un ricalcolo delle tasse.
- Formattazione Valuta: I prezzi sono sempre restituiti come interi nell’unità di valuta più piccola (ad esempio, centesimi per USD, yen per JPY). Per visualizzarli, dividere per 100 (o la potenza di 10 appropriata) o utilizzare una libreria di formattazione come
Intl.NumberFormat. - Gestione degli Stati Iniziali: Quando il checkout si carica per la prima volta,
taxediscountpossono essere0onullfino a quando l’utente non fornisce le proprie informazioni di fatturazione o applica un codice. La tua interfaccia utente dovrebbe gestire questi stati con grazia (ad esempio, mostrando un trattino—o nascondendo la riga). - Il “Totale Finale” vs “Totale”: Mentre
totalti offre il calcolo standard del prezzo,finalTotalè la fonte di verità per la transazione. SefinalTotalè presente, riflette esattamente cosa verrà addebitato alla carta del cliente, inclusi eventuali aggiustamenti dinamici. - Feedback in Tempo Reale: Utilizza il campo
taxper mostrare agli utenti che le tasse vengono calcolate in tempo reale. Questo fornisce un aspetto “live” alla tua pagina di checkout e riduce l’attrito durante il passaggio di inserimento indirizzo.
Opzioni di Implementazione
Installazione con Gestore Pacchetti
Installa tramite npm, yarn o pnpm come mostrato nella Guida all’Integrazione Passo-Passo.Implementazione via CDN
Per un’integrazione rapida senza un passaggio di build, puoi usare il nostro CDN:Aggiorna Metodo di Pagamento
Il checkout inline supporta aggiornamenti dei metodi di pagamento per gli abbonamenti. Quando un cliente deve aggiornare il proprio metodo di pagamento, sia per un abbonamento attivo che per riattivare un abbonamento sospeso, puoi rendere disponibile il flusso di aggiornamento direttamente all’interno del layout della tua pagina.Come Funziona
- Chiama l’API di Aggiornamento Metodo di Pagamento per ottenere un
payment_link:
- Passa l’
payment_linkrestituito comecheckoutUrlper aprire il checkout inline:
Per Abbonamenti Sospesi
Quando si aggiorna il metodo di pagamento per un abbonamento 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 Errori
L’SDK fornisce informazioni dettagliate sugli errori attraverso il sistema degli eventi. Implementa sempre un’adeguata gestione degli errori nel tuo callbackonEvent:
Best Practices
- Design Reattivo: Assicurati che il tuo elemento contenitore abbia abbastanza larghezza e altezza. L’iframe si espanderà tipicamente per riempire il suo contenitore.
- Sincronizzazione: Usa l’evento
checkout.breakdownper mantenere il tuo riepilogo ordine personalizzato o le tabelle dei prezzi sincronizzate con ciò che l’utente vede nel frame di checkout. - Stati Skeleton: Mostra un indicatore di caricamento nel tuo contenitore fino a quando l’evento
checkout.openedviene attivato. - Pulizia: Chiama
DodoPayments.Checkout.close()quando il tuo componente viene smontato per pulire l’iframe e i listener di eventi.
#0d0d0d come colore di sfondo per un’integrazione visiva ottimale con il frame di checkout inline.Validazione dello Stato di Pagamento
Perché la Validazione Server-Side è Essenziale
Sebbene gli eventi di checkout inline forniscano feedback in tempo reale, non dovrebbero mai essere la tua unica fonte di verità per lo stato dei pagamenti. Problemi di rete, crash del browser o chiusura della pagina da parte degli utenti possono causare la perdita di eventi. Per garantire una valida verifica del pagamento:- Il tuo server dovrebbe ascoltare gli eventi webhook - Dodo Payments invia webhook per le modifiche di stato del pagamento
- Implementa un meccanismo di polling - Il tuo frontend dovrebbe eseguire il polling del tuo server per aggiornamenti di stato
- Combina entrambi gli approcci - Usa i webhook come fonte principale e il polling come fallback
Architettura Raccomandata
Passaggi di Implementazione
1. Ascolta gli eventi di checkout - Quando l’utente clicca su paga, inizia a prepararti per verificare lo stato:payment.succeeded o payment.failed. Vedi la nostra documentazione sui Webhook per i dettagli.
Risoluzione dei Problemi
Checkout frame is not appearing
Checkout frame is not appearing
- Verifica che
elementIdcorrisponda aliddi undivche esiste realmente nel DOM. - Assicurati che
displayType: 'inline'sia 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 sono calcolate solo dopo che l’utente inserisce un paese e un codice postale validi nel frame del checkout.
Abilitazione dei Portafogli Digitali
Per informazioni dettagliate su come configurare Apple Pay, Google Pay e altri portafogli digitali, vedere la pagina sui Portafogli Digitali.Configurazione Rapida per Apple Pay
Open Wallet domains

Open Wallet domains from the Apple Pay row
Download the domain association file

Download the Apple Pay domain association file
Register your domain
shop.example.com), quindi fai clic su Continue.
Register the domain where you embed inline checkout
Host the file on your domain
Content-Type: application/octet-stream o text/plain.Verify the domain

Verify the hosted association file
Confirm it's active

Verified domains show an Active status
Test the integration
- Apri il checkout su un dispositivo Apple
- Verifica che venga visualizzato il pulsante Apple Pay
- Completa una transazione di test
Browser Support
Dodo Payments Checkout SDK supporta i seguenti browser:- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- IE11+