Overlay Checkout - Dodo Payments Documentation

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.

Immagine di copertina del checkout sovrapposto

Demo

Interactive Demo

Guarda il checkout sovrapposto in azione con la nostra demo dal vivo.

Inizio rapido

Inizia con il Dodo Payments Checkout SDK in poche righe di codice:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Ottieni l’URL del tuo checkout dall’API di creazione della sessione di checkout.

Guida all’integrazione passo-passo

Install the SDK

Installa il Dodo Payments Checkout SDK utilizzando il tuo gestore di pacchetti preferito:

npm install dodopayments-checkout

Initialize the SDK

Inizializza l’SDK nella tua applicazione, tipicamente nel tuo componente principale o nel punto di ingresso dell’app:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Inizializza sempre l’SDK prima di cercare di aprire il checkout. L’inizializzazione dovrebbe avvenire una sola volta quando la tua applicazione viene caricata.

Create a Checkout Button Component

Crea un componente che apre l’overlay di checkout:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add Checkout to Your Page

Usa il componente pulsante di checkout nella tua applicazione:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Success and Failure Pages

Crea pagine per gestire i reindirizzamenti del checkout:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

Avvia il tuo server di sviluppo:

npm run dev

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 del checkout registrati nella console del browser.

Go Live

Quando sei pronto per la produzione:

Cambia la modalità in 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

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

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

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 del checkout

Opzioni di checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

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 nasconde il timer del checkout. Il valore predefinito è `true`. Quando disabilitato, riceverai l’evento `checkout.link_expired` quando la sessione scade.
`options.showSecurityBadge`	`boolean`	No	Mostra o nasconde il badge di sicurezza. Il valore predefinito è `true`.
`options.manualRedirect`	`boolean`	No	Quando abilitato, il checkout non reindirizzerà automaticamente dopo il completamento. Riceverai invece gli eventi `checkout.status` e `checkout.redirect_requested` per gestire tu stesso il reindirizzamento.

Metodi

Apri Checkout

Apre l’overlay di checkout con l’URL della sessione di checkout specificato.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Puoi anche passare opzioni aggiuntive per personalizzare il comportamento del checkout:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

Quando utilizzi manualRedirect, gestisci il completamento del checkout nella tua callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Chiudi Checkout

Chiude programmaticamente l’overlay di checkout.

DodoPayments.Checkout.close();

Controlla Stato

Restituisce se l’overlay di checkout è attualmente aperto.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Eventi

L’SDK fornisce eventi in tempo reale ai quali puoi ascoltare tramite la callback onEvent:

Dati Evento Stato Checkout

Quando manualRedirect è abilitato, ricevi l’evento checkout.status con i seguenti dati:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Dati Evento Reindirizzamento Checkout Richiesto

Quando manualRedirect è abilitato, ricevi l’evento checkout.redirect_requested con i seguenti dati:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Tipo di evento	Descrizione
`checkout.opened`	L’overlay del checkout è stato aperto
`checkout.form_ready`	Il modulo di checkout è pronto per ricevere l’input dell’utente. Utile per nascondere gli stati di caricamento.
`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 del checkout è stato chiuso
`checkout.redirect`	Il checkout eseguirà un reindirizzamento
`checkout.error`	Si è verificato un errore durante il checkout
`checkout.link_expired`	Viene attivato quando la sessione di checkout scade. Viene ricevuto solo quando `showTimer` è impostato su `false`.
`checkout.status`	Viene attivato quando `manualRedirect` è abilitato. Contiene lo stato del checkout (`succeeded`, `failed` o `processing`).
`checkout.redirect_requested`	Viene attivato quando `manualRedirect` è abilitato. Contiene l’URL al quale 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:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Personalizzazione del Tema

Puoi personalizzare l’aspetto del checkout passando un oggetto themeConfig nel parametro options quando apri il checkout. La configurazione del tema supporta sia la modalità chiara sia quella scura, consentendoti di personalizzare colori, bordi, testi, pulsanti e raggio dei bordi.

Questa sezione copre la configurazione del tema lato client utilizzando il Checkout SDK. Puoi anche configurare i temi lato server quando crei una sessione di checkout tramite l’API usando il parametro theme_config. Consulta Checkout Theme Customization per la configurazione a livello API, oppure usa la pagina Design nel dashboard per configurare visivamente i temi con anteprima live.

Configurazione base del tema

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Configurazione completa del tema

Tutte le proprietà del tema disponibili:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Solo modalità chiara

Se desideri personalizzare solo il tema chiaro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Solo modalità scura

Se desideri personalizzare solo il tema scuro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Sovrascrittura parziale del tema

Puoi sovrascrivere solo determinate proprietà. Il checkout utilizzerà i valori predefiniti per le proprietà che non specifichi:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Configurazione del tema con altre opzioni

Puoi combinare la configurazione del tema con altre opzioni di checkout:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Tipi TypeScript

Per gli utenti TypeScript, tutti i tipi di configurazione del tema sono esportati:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Gestione degli errori

L’SDK fornisce informazioni dettagliate sugli errori tramite il sistema di eventi. Implementa sempre una corretta gestione degli errori nella tua callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

Gestisci sempre l’evento checkout.error per garantire una buona esperienza utente quando si verificano errori.

Best Practice

Inizializza una volta: inizializza l’SDK una sola volta quando la tua applicazione viene caricata, non ad ogni tentativo di checkout
Gestione degli errori: implementa sempre una corretta gestione degli errori nella tua callback degli eventi
Modalità di test: usa la modalità test durante lo sviluppo e passa a live solo quando sei pronto per la produzione
Gestione degli eventi: gestisci tutti gli eventi rilevanti per offrire un’esperienza utente completa
URL validi: utilizza sempre URL di checkout validi provenienti dall’API di creazione della sessione di checkout
TypeScript: usa TypeScript per una migliore sicurezza dei tipi e esperienza di sviluppo
Stati di caricamento: mostra stati di caricamento mentre il checkout si apre per migliorare l’UX
Reindirizzamenti manuali: usa manualRedirect quando hai bisogno di un controllo personalizzato sulla navigazione post-checkout
Gestione del timer: disabilita il timer (showTimer: false) se vuoi gestire manualmente la scadenza della sessione

Risoluzione dei problemi

Checkout not opening

Possibili cause:

SDK non inizializzato prima di chiamare open()
URL di checkout non valido
Errori JavaScript nella console
Problemi di connettività di rete

Soluzioni:

Verifica che l’inizializzazione dell’SDK avvenga prima di aprire il checkout
Controlla eventuali errori nella console
Assicurati che l’URL del checkout sia valido e proveniente dall’API di creazione della sessione di checkout
Verifica la connettività di rete

Events not firing

Possibili cause:

Il gestore degli eventi non è configurato correttamente
Errori JavaScript che impediscono la propagazione degli eventi
L’SDK non è stato inizializzato correttamente

Soluzioni:

Conferma che il gestore degli eventi sia configurato correttamente in Initialize()
Controlla la console del browser per errori JavaScript
Verifica che l’inizializzazione dell’SDK sia stata completata con successo
Testa prima con un gestore degli eventi semplice

Styling issues

Possibili cause:

Conflitti CSS con gli stili della tua applicazione
Impostazioni del tema non applicate correttamente
Problemi con il design reattivo

Soluzioni:

Controlla eventuali conflitti CSS negli strumenti di sviluppo 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

Abilitazione dei portafogli digitali

Per informazioni dettagliate sulla configurazione di Google Pay e altri portafogli digitali, consulta la pagina Portafogli digitali.

Apple Pay non è ancora supportato nel checkout sovrapposto. Il supporto per Apple Pay arriverà presto.

Supporto del browser

L’SDK Dodo Payments Checkout supporta i seguenti browser:

Chrome (ultima versione)
Firefox (ultima versione)
Safari (ultima versione)
Edge (ultima versione)
IE11+

Checkout sovrapposto vs inline

Scegli il tipo di checkout più adatto al tuo caso d’uso:

Funzionalità	Checkout sovrapposto	Checkout inline
Profondità d’integrazione	Modale sopra la pagina	Totalmente incorporato nella pagina
Controllo del layout	Limitato	Controllo completo
Branding	Separato dalla pagina	Senza soluzione di continuità
Sforzo di implementazione	Minore	Maggiore
Ideale per	Integrazione rapida, pagine esistenti	Pagine di checkout personalizzate, flussi ad alta conversione

Usa il checkout sovrapposto per un’integrazione più veloce con modifiche minime alle pagine esistenti. Usa il checkout inline quando desideri il massimo controllo sull’esperienza di checkout e un branding senza soluzione di continuità.

Risorse correlate

Inline Checkout

Incorporare il checkout direttamente nella tua pagina per esperienze completamente integrate.

Checkout Sessions API

Crea sessioni di checkout per alimentare le tue esperienze di checkout.

Webhooks

Gestisci gli eventi di pagamento lato server con i webhook.

Integration Guide

Guida completa all’integrazione con Dodo Payments.

Per ulteriore assistenza, visita la nostra community Discord o contatta il nostro team di supporto per sviluppatori.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Panoramica

​Demo

Interactive Demo

​Inizio rapido

​Guida all’integrazione passo-passo

​Riferimento API

​Configurazione

​Opzioni di inizializzazione

​Opzioni di checkout

​Metodi

​Apri Checkout

​Chiudi Checkout

​Controlla Stato

​Eventi

​Dati Evento Stato Checkout

​Dati Evento Reindirizzamento Checkout Richiesto

​Opzioni di Implementazione

​Installazione tramite Package Manager

​Implementazione CDN

​Personalizzazione del Tema

​Configurazione base del tema

​Configurazione completa del tema

​Solo modalità chiara

​Solo modalità scura

​Sovrascrittura parziale del tema

​Configurazione del tema con altre opzioni

​Tipi TypeScript

​Gestione degli errori

​Best Practice

​Risoluzione dei problemi

​Abilitazione dei portafogli digitali

​Supporto del browser

​Checkout sovrapposto vs inline

​Risorse correlate

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Panoramica

Demo

Inizio rapido

Guida all’integrazione passo-passo

Riferimento API

Configurazione

Opzioni di inizializzazione

Opzioni di checkout

Metodi

Apri Checkout

Chiudi Checkout

Controlla Stato

Eventi

Dati Evento Stato Checkout

Dati Evento Reindirizzamento Checkout Richiesto

Opzioni di Implementazione

Installazione tramite Package Manager

Implementazione CDN

Personalizzazione del Tema

Configurazione base del tema

Configurazione completa del tema

Solo modalità chiara

Solo modalità scura

Sovrascrittura parziale del tema

Configurazione del tema con altre opzioni

Tipi TypeScript

Gestione degli errori

Best Practice

Risoluzione dei problemi

Abilitazione dei portafogli digitali

Supporto del browser

Checkout sovrapposto vs inline

Risorse correlate