Panoramica
Il Dodo Payments Checkout SDK fornisce un modo fluido per integrare il nostro overlay di pagamento nella tua applicazione web. Costruito con TypeScript e standard web moderni, offre una soluzione robusta per gestire i pagamenti con gestione degli eventi in tempo reale e temi personalizzabili.
Demo
Demo interattiva
Guarda il checkout overlay in azione con la nostra demo dal vivo.
Inizio rapido
Inizia con il Dodo Payments Checkout SDK in poche righe di codice:Guida all’integrazione passo-passo
1
Installa l'SDK
Installa il Dodo Payments Checkout SDK utilizzando il tuo gestore di pacchetti preferito:
2
Inizializza l'SDK
Inizializza l’SDK nella tua applicazione, tipicamente nel tuo componente principale o nel punto di ingresso dell’app:
3
Crea un componente pulsante di checkout
Crea un componente che apre l’overlay di checkout:
4
Aggiungi il checkout alla tua pagina
Usa il componente pulsante di checkout nella tua applicazione:
5
Gestisci le pagine di successo e fallimento
Crea pagine per gestire i reindirizzamenti del checkout:
6
Testa la tua integrazione
- Avvia il tuo server di sviluppo:
- Testa il flusso di checkout:
- Clicca sul pulsante di checkout
- Verifica che l’overlay appaia
- Testa il flusso di pagamento utilizzando credenziali di test
- Conferma che i reindirizzamenti funzionino correttamente
Dovresti vedere gli eventi di checkout registrati nella console del tuo browser.
7
Vai in produzione
Quando sei pronto per la produzione:
- Cambia la modalità in
'live':
- Aggiorna i tuoi URL di checkout per utilizzare sessioni di checkout dal vivo dal tuo backend
- Testa l’intero flusso in produzione
- Monitora eventi ed errori
Riferimento API
Configurazione
Opzioni di inizializzazione
| Opzione | Tipo | Richiesto | Descrizione |
|---|---|---|---|
mode | "test" | "live" | Sì | Modalità ambiente: 'test' per lo sviluppo, 'live' per la produzione |
displayType | "overlay" | "inline" | No | Tipo di visualizzazione: 'overlay' per il checkout modale (predefinito), 'inline' per il checkout incorporato |
onEvent | function | Sì | Funzione di callback per gestire gli eventi di checkout |
Opzioni di checkout
| Opzione | Tipo | Richiesto | Descrizione |
|---|---|---|---|
checkoutUrl | string | Sì | URL della sessione di checkout dall’API di creazione della sessione di checkout |
options.showTimer | boolean | No | Mostra o nascondi il timer di checkout. Predefinito a true. Quando disabilitato, riceverai l’evento checkout.link_expired quando la sessione scade. |
options.showSecurityBadge | boolean | No | Mostra o nascondi il badge di sicurezza. Predefinito a true. |
options.manualRedirect | boolean | No | Quando abilitato, il checkout non verrà reindirizzato automaticamente dopo il completamento. Invece, riceverai gli eventi checkout.status e checkout.redirect_requested per gestire il reindirizzamento tu stesso. |
Metodi
Apri Checkout
Apre l’overlay di checkout con l’URL della sessione di checkout specificato.manualRedirect, gestisci il completamento del checkout nella tua funzione di callback onEvent:
Chiudi Checkout
Chiude programmaticamente l’overlay di checkout.Controlla Stato
Restituisce se l’overlay di checkout è attualmente aperto.Eventi
L’SDK fornisce eventi in tempo reale a cui puoi ascoltare tramite la funzione di callbackonEvent:
Dati Evento Stato Checkout
QuandomanualRedirect è abilitato, ricevi l’evento checkout.status con i seguenti dati:
Dati Evento Reindirizzamento Checkout Richiesto
QuandomanualRedirect è abilitato, ricevi l’evento checkout.redirect_requested con i seguenti dati:
| Tipo di Evento | Descrizione |
|---|---|
checkout.opened | L’overlay di checkout è stato aperto |
checkout.payment_page_opened | La pagina di pagamento è stata visualizzata |
checkout.customer_details_submitted | I dettagli del cliente e di fatturazione sono stati inviati |
checkout.closed | L’overlay di checkout è stato chiuso |
checkout.redirect | Il checkout eseguirà un reindirizzamento |
checkout.error | Si è verificato un errore durante il checkout |
checkout.link_expired | Attivato quando la sessione di checkout scade. Ricevuto solo quando showTimer è impostato su false. |
checkout.status | Attivato quando manualRedirect è abilitato. Contiene lo stato del checkout (succeeded, failed, o processing). |
checkout.redirect_requested | Attivato quando manualRedirect è abilitato. Contiene l’URL a cui reindirizzare il cliente. |
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 passaggi di build, puoi utilizzare il nostro CDN:Personalizzazione del Tema
Puoi personalizzare l’aspetto del checkout passando un oggettothemeConfig nel parametro options quando apri il checkout. La configurazione del tema supporta sia modalità chiare che scure, consentendoti di personalizzare colori, bordi, testo, pulsanti e raggio dei bordi.
Configurazione di Base del Tema
Configurazione Completa del Tema
Tutte le proprietà del tema disponibili:Solo Modalità Chiara
Se desideri personalizzare solo il tema chiaro:Solo Modalità Scura
Se desideri personalizzare solo il tema scuro:Sovrascrittura Parziale del Tema
Puoi sovrascrivere solo proprietà specifiche. Il checkout utilizzerà valori predefiniti per le proprietà che non specifichi:Configurazione del Tema con Altre Opzioni
Puoi combinare la configurazione del tema con altre opzioni di checkout:Tipi TypeScript
Per gli utenti TypeScript, tutti i tipi di configurazione del tema sono esportati:Gestione degli Errori
L’SDK fornisce informazioni dettagliate sugli errori attraverso il sistema di eventi. Implementa sempre una corretta gestione degli errori nel tuo callbackonEvent:
Migliori Pratiche
- Inizializza una sola volta: Inizializza l’SDK una sola volta quando la tua applicazione si carica, non ad ogni tentativo di checkout
- Gestione degli errori: Implementa sempre una corretta gestione degli errori nel tuo callback degli eventi
- Modalità di test: Usa la modalità
testdurante lo sviluppo e passa alivesolo quando sei pronto per la produzione - Gestione degli eventi: Gestisci tutti gli eventi rilevanti per un’esperienza utente completa
- URL validi: Usa sempre URL di checkout validi dall’API di creazione della sessione di checkout
- TypeScript: Usa TypeScript per una migliore sicurezza dei tipi e un’esperienza di sviluppo migliore
- Stati di caricamento: Mostra stati di caricamento mentre il checkout si apre per migliorare l’UX
- Redirect manuali: Usa
manualRedirectquando hai bisogno di un controllo personalizzato sulla navigazione post-checkout - Gestione del timer: Disabilita il timer (
showTimer: false) se desideri gestire manualmente la scadenza della sessione
Risoluzione dei Problemi
Il checkout non si apre
Il checkout non si apre
Possibili cause:
- SDK non inizializzato prima di chiamare
open() - URL di checkout non valido
- Errori JavaScript nella console
- Problemi di connettività di rete
- Verifica che l’inizializzazione dell’SDK avvenga prima di aprire il checkout
- Controlla gli errori nella console
- Assicurati che l’URL di checkout sia valido e provenga dall’API di creazione della sessione di checkout
- Verifica la connettività di rete
Eventi non attivati
Eventi non attivati
Possibili cause:
- Gestore dell’evento non configurato correttamente
- Errori JavaScript che impediscono la propagazione dell’evento
- SDK non inizializzato correttamente
- Conferma che il gestore dell’evento sia configurato correttamente in
Initialize() - Controlla la console del browser per errori JavaScript
- Verifica che l’inizializzazione dell’SDK sia completata con successo
- Testa prima con un gestore di eventi semplice
Problemi di stile
Problemi di stile
Possibili cause:
- Conflitti CSS con gli stili della tua applicazione
- Impostazioni del tema non applicate correttamente
- Problemi di design responsivo
- Controlla i conflitti CSS negli strumenti per sviluppatori del browser
- Verifica che le impostazioni del tema siano corrette
- Testa su diverse dimensioni dello schermo
- Assicurati che non ci siano conflitti di z-index con l’overlay
Abilitare Apple Pay
Apple Pay consente ai clienti di completare i pagamenti rapidamente e in modo sicuro utilizzando i loro metodi di pagamento salvati. Quando abilitato, i clienti possono avviare il modulo Apple Pay direttamente dall’overlay del checkout su dispositivi supportati.Apple Pay è supportato su iOS 17+, iPadOS 17+ e Safari 17+ su macOS.
1
Scarica e carica il file di associazione del dominio Apple Pay
Scarica il file di associazione del dominio Apple Pay.Carica il file sul tuo server web in
/.well-known/apple-developer-merchantid-domain-association. Ad esempio, se il tuo sito web è example.com, rendi il file disponibile in https://example.com/well-known/apple-developer-merchantid-domain-association.2
Richiedi l'attivazione di Apple Pay
Invia un’email a [email protected] con le seguenti informazioni:
- L’URL del tuo dominio di produzione (ad es.,
https://example.com) - Richiesta di abilitare Apple Pay per il tuo dominio
Riceverai conferma entro 1-2 giorni lavorativi una volta che Apple Pay è stato abilitato per il tuo dominio.
3
Verifica la disponibilità di Apple Pay
Dopo aver ricevuto conferma, testa Apple Pay nel tuo checkout:
- Apri il tuo checkout su un dispositivo supportato (iOS 17+, iPadOS 17+ o Safari 17+ su macOS)
- Verifica che il pulsante Apple Pay appaia come opzione di pagamento
- Testa l’intero flusso di pagamento
Supporto del Browser
L’SDK di Dodo Payments Checkout supporta i seguenti browser:- Chrome (ultimissima versione)
- Firefox (ultimissima versione)
- Safari (ultimissima versione)
- Edge (ultimissima versione)
- IE11+
Checkout Overlay vs Inline
Scegli il tipo di checkout giusto per il tuo caso d’uso:| Caratteristica | Checkout Overlay | Checkout Inline |
|---|---|---|
| Profondità di integrazione | Modale sopra la pagina | Completamente integrato nella pagina |
| Controllo del layout | Limitato | Controllo completo |
| Branding | Separato dalla pagina | Senza soluzione di continuità |
| Sforzo di implementazione | Inferiore | Superiore |
| Migliore per | Integrazione rapida, pagine esistenti | Pagine di checkout personalizzate, flussi ad alta conversione |
Risorse Correlate
Checkout Inline
Integra direttamente il checkout nella tua pagina per esperienze completamente integrate.
API delle Sessioni di Checkout
Crea sessioni di checkout per alimentare le tue esperienze di checkout.
Webhooks
Gestisci eventi di pagamento lato server con i webhooks.
Guida all'Integrazione
Guida completa per integrare Dodo Payments.